PD-2433 / 25.10 / Pd 2433 update 2 fa content for behavioral changes

content/SCALETutorials/Credentials/ManageUsers.md

@@ -115,3 +115,48 @@ To set the API key to expire, clear the checkmark in **Non-expiring**, then sele
 {{< trueimage src="/images/SCALE/Credentials/AddAPIKeyExpiration.png" alt="Set API Key Expiration" id="Set API Key Expiration" >}}
 
 After setting the date, click **Save**. The **Access** widget for this user shows the API Key icon and the **View API Keys** link.
+
+## Clearing Two-Factor Authentication for a User
+
+Administrators can clear two-factor authentication (2FA) for a user from the **Users** screen. This is typically necessary when:
+
+- A user has lost access to their authenticator device (lost phone, broken device, etc.)
+- A user cannot generate valid 2FA codes due to device time synchronization issues
+- A user needs to switch to a different authenticator app or device
+- Troubleshooting 2FA-related login problems
+
+{{< hint type=important >}}
+Clearing 2FA should only be done when necessary, as it temporarily reduces account security. When Global 2FA is enabled, users are prompted to reconfigure 2FA on their next login.
+{{< /hint >}}
+
+To clear 2FA for a user:
+
+1. Go to **Credentials > Users**.
+
+2. Click on the user row to select the user whose 2FA needs to be cleared.
+
+3. On the **Access** widget, click **Clear Two-Factor Authentication**.
+
+   {{< trueimage src="/images/SCALE/Credentials/UsersScreenAccessWidgetWithAPIKey.png" alt="Access Widget with Clear 2FA Button" id="Access Widget with Clear 2FA Button" >}}
+
+   {{< hint type=note >}}
+   The **Clear Two-Factor Authentication** button only appears for users who have 2FA configured. Users without 2FA configured do not show this button.
+   {{< /hint >}}
+
+4. A confirmation dialog appears asking if you want to clear two-factor authentication settings for this user.
+
+   {{< trueimage src="/images/SCALE/Credentials/Clear2FADialog.png" alt="Clear Two-Factor Authentication Dialog" id="Clear Two-Factor Authentication Dialog" >}}
+
+5. Click **Clear** to confirm, or **Cancel** to abort the operation.
+
+After clearing, the user can log in without 2FA codes. If Global 2FA is enabled on the system, the user is prompted to set up 2FA again on their next login.
+
+### User Self-Clearing vs Admin Clearing
+
+Users can also remove their own 2FA configuration using the **Settings** menu:
+
+- User self-clearing: The logged-in user accesses **Settings > Two-Factor Authentication** and clicks **Unset 2FA Secret**. This allows users to manage their own 2FA settings.
+
+- Admin clearing: Administrators use **Credentials > Users > Access Widget > Clear Two-Factor Authentication** to clear 2FA for another user. This is specifically for helping users who cannot access their accounts.
+
+For more information on 2FA configuration and management, see [Managing Global 2FA]({{< ref "ManageGlobal2FASCALE" >}}).

content/SCALETutorials/SystemSettings/Advanced/ManageGlobal2FASCALE.md

@@ -19,9 +19,18 @@ TrueNAS offers global 2FA to ensure that entities cannot use a compromised admin
 {{< include file="/static/includes/AdvancedSettingsWarningSCALE.md" >}}
 
 ## About TrueNAS 2FA
-To use 2FA, you need a mobile device with the current time and date, and an authenticator app installed.
-We recommend Google Authenticator.
-You can use other authenticator applications, but you must confirm the settings, unique keys, and QR codes generated in TrueNAS are compatible with your particular app before permanently activating 2FA.
+
+To use 2FA, you need a mobile device (or desktop application) with the correct time and date, and a TOTP-compatible authenticator app installed.
+
+TrueNAS uses the TOTP (Time-based One-Time Password) standard (RFC 6238), which is compatible with most authenticator apps. Popular options include:
+
+- **Microsoft Authenticator** (iOS, Android)
+- **Google Authenticator** (iOS, Android)
+- **Authy** (iOS, Android, desktop)
+- **Bitwarden** (cross-platform, open source)
+- **1Password** (cross-platform)
+
+Choose an authenticator app based on your platform and preferences. All TOTP-compatible apps work with TrueNAS.
 
 {{< hint type=important >}}
 Two-factor authentication is time-based and requires a correct system time setting.
@@ -34,89 +43,176 @@ We strongly recommend ensuring Network Time Protocol (NTP) is functional before
 {{< /expand >}}
 
 ### Benefits of 2FA
+
 Unauthorized users cannot log in since they do not have the randomized six-digit code.
 
 Authorized employees can securely access systems from any device or location without jeopardizing sensitive information.
 
 Internet access on the TrueNAS system is not required to use 2FA.
 
 ### Drawbacks of 2FA
+
 2FA requires an app to generate the 2FA code.
 
 If the 2FA code is not working or users cannot get it, the system is inaccessible through the UI and SSH (if enabled).
-You can bypass or [unlock 2FA](#disabling-or-bypassing-2fa) using the CLI.
+You can bypass or [unlock 2FA](#disabling-global-2fa) using the CLI.
+
+## Enabling Global 2FA
 
-## Enabling 2FA
 {{< hint type=warning >}}
 Set up a second 2FA device as a backup before proceeding.
 {{< /hint >}}
 
-Before you begin, download Google Authenticator to your mobile device.
+Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See [About TrueNAS 2FA](#about-truenas-2fa) for recommended options.
 
 1. Go to **System > Advanced Settings**, scroll down to the **Global Two Factor Authentication** widget, and click **Configure**.
 
-   {{< trueimage src="/images/SCALE/SystemSettings/GlobalTwoFactorAuthenticationWidget.png" alt="Global TwoFactor Authentication Widget" id="1 - Global Two Factor Authentication Settings Widget" >}}
+   {{< trueimage src="/images/SCALE/SystemSettings/GlobalTwoFactorAuthenticationWidget.png" alt="Global TwoFactor Authentication Widget" id="Global Two Factor Authentication Settings Widget" >}}
 
 2. Check **Enable Two Factor Authentication Globally**, then click **Save**.
 
    {{< trueimage src="/images/SCALE/SystemSettings/Enable2FAGlobally.png" alt="Enable2FAGlobally" id="Check Enable Two Factor Authentication Globally" >}}
 
    If you want to enable two-factor authentication for SSH logins, select **Enable Two-Factor Auth for SSH** before you click **Save**.
 
-   TrueNAS takes you to the **Two-Factor Authentication** screen to finish 2FA setup.
+   {{< hint type=tip >}}
+   The **Window** setting extends the validity of authentication codes to include previously generated codes. This can be helpful in high-latency situations where there can be delays between code generation and entry. The default setting works for most environments - only adjust this if users experience authentication issues due to network delays.
+   {{< /hint >}}
 
-   You can also access the two-factor authentication settings for the currently logged-in user from the **Settings** option on the top toolbar.
-   Click the **Settings** icon, then select **Two-Factor Authentication** to open the **User Two-Factor Authentication Actions** screen.
+After enabling Global 2FA, the system prompts users to set up their individual 2FA configuration:
+
+- Accounts that are already configured with individual 2FA are not prompted for 2FA login codes until **Global 2FA** is enabled.
+- When **Global 2FA** is enabled, user accounts without 2FA settings configured are prompted with the **Two-Factor Authentication** screen on their next login to set up 2FA authentication for that account.
+
+See [Setting Up Individual 2FA](#setting-up-individual-2fa) for detailed instructions on configuring 2FA for individual user accounts.
+
+### Disabling Global 2FA
+
+Go to **System > Advanced Settings**, scroll down to the **Global Two Factor Authentication** widget, and click **Config**. Clear the **Enable Two-Factor Authentication Globally** checkbox and click **Save**.
+
+### Reactivating Global 2FA
+
+If you want to enable 2FA again, go to **System > Advanced Settings**, scroll down to the **Global Two Factor Authentication** widget, and click **Config**.
+
+Check **Enable Two Factor Authentication Globally**, then click **Save**.
+To change the system-generated **Secret**, click on the **Settings** icon on the top toolbar and select **Two-Factor Authentication**.
+Click **Renew 2FA Secret**.
+
+## Setting Up Individual 2FA
+
+When administrators enable Global 2FA, users without 2FA configured are prompted to set it up on their next login. Users can also set up 2FA at any time by accessing **Settings > Two-Factor Authentication** from the top toolbar.
+
+{{< hint type=warning >}}
+Set up a second 2FA device as a backup before proceeding.
+{{< /hint >}}
+
+Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See [About TrueNAS 2FA](#about-truenas-2fa) for recommended options.
+
+**To set up individual 2FA:**
+
+1. Click the **Settings** icon on the top toolbar, then select **Two-Factor Authentication** to open the **User Two-Factor Authentication Actions** screen.
 
    {{< trueimage src="/images/SCALE/SystemSettings/UserTwoFactorAuthenticationActionsScreen.png" alt="User Two-Factor Authentication Actions Screen" id="User Two-Factor Authentication Actions Screen" >}}
 
-   Click **Configure 2FA Secret** to open the **Set Up Two-Factor Authentication** screen and view the QR code.  The **Set Up Two-Factor Authentication** screen also has the unique key with a copy to clipboard button so you can configure 2FA using a non-camera method if necessary.
+2. Click **Configure 2FA Secret** to open the **Set Up Two-Factor Authentication** screen and view the QR code. The **Set Up Two-Factor Authentication** screen also has the unique key with a copy to clipboard button so you can configure 2FA using a non-camera method if necessary.
 
    {{< hint type="info">}}
    You can configure two-factor authentication and get the QR code for an authenticator app for the logged-in user at any time, but you must configure global two-factor authentication to enable it.
    {{< /hint >}}
-
-   When using Google Authenticator, set **Interval** to **30** or the authenticator code might not function when logging in.
 
-3. Click **Configure 2FA Secret** to open the **Set Up Two-Factor Authentication** screen where you scan the QR code using Google Authenticator or copy the unique key.
+   Set **Interval** to **30** seconds to match the default setting used by most authenticator apps. Using a non-standard interval can cause authentication codes to fail during login.
+
+3. Scan the QR code using your authenticator app or manually enter the unique key.
    To generate a new QR code click **Renew 2FA Secret**.
 
    {{< trueimage src="/images/SCALE/SystemSettings/SetUpTwoFactorAuthenticationScreen.png" alt="Set Up Two-Factor Authentication Screen" id="Set Up Two-Factor Authentication Screen" >}}
 
-   After scanning the code click **Finish** to close the dialog on the **Two-Factor Authentication** screen.
+4. After scanning the code:
+   - **If prompted during login**: Click **Finish** to close the setup dialog.
+   - **If accessing from the Settings menu**: Your configuration is saved automatically. You can navigate to other screens as needed.
 
-Accounts that are already configured with individual 2FA are not prompted for 2FA login codes until **Global 2FA** is enabled.
-When **Global 2FA** is enabled, user accounts without 2FA settings configured see the **Two-Factor Authentication** screen on their next login to configure and enable 2FA authentication for that account.
+Your 2FA is now configured. You need to enter codes from your authenticator app when logging in.
 
-### Disabling or Bypassing 2FA
-Go to **System > Advanced Settings**, scroll down to the **Global Two Factor Authentication** widget, and click **Config**. Clear the **Enable Two-Factor Authentication Globally** checkbox and click **Save**.
+If you prefer not to set up 2FA at this time, see [Skipping 2FA Setup](#skipping-2fa-setup).
 
-### Reactivating 2FA
-If you want to enable 2FA again, go to **System > Advanced Settings**, scroll down to the **Global Two Factor Authentication** widget, and click **Config**.
+### Skipping 2FA Setup
 
-Check **Enable Two Factor Authentication Globally**, then click **Save**.
-To change the system-generated **Secret**, click on the **Settings** icon on the top toolbar and select **Two-Factor Authentication**. 
-Click **Renew 2FA Secret**.
+When administrators enable **Global 2FA**, users without 2FA configured are prompted to set it up on their next login. However, individual setup is optional and can be skipped. See [Setting Up Individual 2FA](#setting-up-individual-2fa) for the full setup process.
+
+To skip the setup:
+
+1. When the **Two-Factor Authentication** setup screen appears, click **Skip Setup**.
+2. Confirm the decision in the dialog that appears.
+
+{{< hint type=note >}}
+While 2FA significantly enhances security and is strongly recommended, skipping the initial setup does not prevent access to the system. Users can configure 2FA later by accessing **Settings > Two-Factor Authentication** from the top toolbar.
+{{< /hint >}}
+
+The setup prompt appears once per login session. If you skip setup, you are prompted again on your next login until you configure 2FA.
+
+### Removing Individual 2FA Configuration
+
+Users can remove their personal 2FA configuration without disabling global 2FA:
+
+1. Click the **Settings** icon on the top toolbar and select **Two-Factor Authentication**.
+2. Click **Unset 2FA Secret**.
+3. Confirm the removal when prompted.
+
+{{< hint type=warning >}}
+Removing 2FA configuration reduces account security. Only remove 2FA if you plan to reconfigure it with a different authenticator device, or if you no longer have access to your current authenticator.
+{{< /hint >}}
+
+After removing your 2FA configuration:
+
+- If **Global 2FA** is still enabled, you are prompted to set up 2FA again on your next login
+- You can skip this prompt if needed using the **Skip Setup** button
+- 2FA configurations for other users remain unaffected
+
+### Administrator Clearing User 2FA
+
+Administrators can clear 2FA for any user without needing to log in as that user. This is useful when:
+
+- A user has lost access to their authenticator device
+- A user is locked out due to 2FA issues
+- Troubleshooting login problems for users
+
+To clear 2FA for another user:
+
+1. Go to **Credentials > Users**
+2. Select the user whose 2FA needs to be cleared
+3. Click **Clear Two-Factor Authentication** on the **Access** widget
+4. Confirm the action in the dialog
+
+After clearing, the user can log in without 2FA. If Global 2FA is still enabled, they are prompted to reconfigure 2FA on their next login.
+
+For detailed step-by-step instructions, see [Managing Users - Clearing Two-Factor Authentication for a User]({{< ref "ManageUsers#clearing-two-factor-authentication-for-a-user" >}}).
+
+{{< hint type=tip >}}
+The **Clear Two-Factor Authentication** button only appears for users who have 2FA configured. If you do not see the button, the user has not set up 2FA.
+{{< /hint >}}
 
 ## Using 2FA to Log in to TrueNAS
+
 Enabling 2FA changes the login process for both the TrueNAS web interface and SSH logins.
 
 ### Logging In Using the Web Interface
+
 The login screen adds another field for the randomized authenticator code. If this field is not immediately visible, try refreshing the browser.
 
 Enter the code from the mobile device (without the space) in the login window and use the admin username and password.
 
 {{< trueimage src="/images/SCALE/Login/2faSigninSplashScreen.png" alt="2FA Signin Splash Screen" id="2FA Splash Screen" >}}
 
-If you wait too long, a new number code displays in Google Authenticator so you can retry.
+TOTP codes regenerate every 30 seconds (by default). If a code expires while you are entering it, wait for your authenticator app to display a new code and retry.
 
 ### Logging In Using SSH
+
 1. Confirm that you set **Enable Two-Factor Auth for SSH** in **System > Advanced > Global Two Factor Authentication**.
 
 2. Go to **Credentials > Users** and edit the desired user account. Set **SSH password login enabled**, then click **Save**.
 
 3. Go to **System Settings > Services** and click the **SSH** <span class="iconify" data-icon="mdi:play-circle" title="Start Service">Start Service</span> button to start the service. Wait for the service status to show that it is running.
 
-4. Open the Google Authentication app on your mobile device.
+4. Open your authenticator app on your mobile device or desktop.
 
 5. Open a terminal (such as Windows Shell) and SSH into the system using either the host name or IP address, the administrator account user name and password, and the 2FA code.

content/SCALEUIReference/Credentials/UsersScreen.md

@@ -139,6 +139,16 @@ When the user has an API key, **View API Keys** shows and opens the **user API K
 **Lock User** opens a confirmation dialog before locking the user. A locked user is prevented from logging in or using password-based services while locked.
 This button toggles to **Unlock User**, which shows a confirmation dialog before unlocking the user.
 
+**Clear Two-Factor Authentication** shows when the user has 2FA configured. Opens a confirmation dialog before clearing the two-factor authentication settings for the user.
+This administrative function helps users who have lost access to their authenticator device or are experiencing 2FA-related login issues.
+When cleared, the user can log in without 2FA. If Global 2FA is enabled, the user is prompted to reconfigure 2FA on their next login.
+
+{{< trueimage src="/images/SCALE/Credentials/Clear2FADialog.png" alt="Clear Two-Factor Authentication Dialog" id="Clear Two-Factor Authentication Dialog" >}}
+
+{{< hint type=important >}}
+Clearing 2FA for a user should only be done when necessary, such as when the user has lost access to their authenticator device. This action temporarily reduces account security until 2FA is reconfigured.
+{{< /hint >}}
+
 ## Add or Edit User Screens
 
 The **Add User** and **Edit User** configuration screens show the same setting options, but a few options are not editable.

content/SCALEUIReference/SystemSettings/AdvancedSettingsScreen.md

@@ -468,8 +468,8 @@ The **Global Two Factor Authentication** widget shows the status of global two-f
 {{< truetable >}}
 | Name | Description |
 |------|-------------|
-| **Enable Two-Factor Authentication Globally** | Select to enable 2FA for the system. |
-| **Window** | Enter the number of valid passwords. Extends password validity beyond the current to the previous password(s) based on the number entered. For example, setting this to **1** means the current and previous passwords are valid. If the previous password is *a* and the current password is *b*, then both passwords are valid. If set to **2**, the current password (*c* ) and the two previous passwords (*a* and *b*) are valid. Setting this to **3** works the same. Extending the window is useful in high-latency situations. |
+| **Enable Two-Factor Authentication Globally** | Select to prompt users to set up 2FA for the system. When enabled, users without 2FA configured are prompted to set it up on their next login. Users can skip the initial setup if needed. |
+| **Window** | Enter the number of valid authentication codes (tolerance window). Extends code validity beyond the current to the previous code(s) based on the number entered. For example, setting this to **1** means the current and previous codes are valid. If the previous code is *a* and the current code is *b*, then both codes are valid. If set to **2**, the current code (*c*) and the two previous codes (*a* and *b*) are valid. Setting this to **3** works the same. Extending the window is useful in high-latency situations. |
 | **Enable Two-Factor Auth for SSH** | Select to enable 2FA for system SSH access. Leave this disabled until you complete a successful test of 2FA with the UI. |
 {{< /truetable >}}
 {{< /expand >}}