truenas · bugclerk · Dec 1, 2025 · Dec 2, 2025 · Dec 1, 2025 · Dec 2, 2025
@@ -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" >}}).
@@ -22,25 +22,17 @@ TrueNAS offers global 2FA to ensure that entities cannot use a compromised admin
 
 ## About TrueNAS 2FA
 
-TrueNAS offers two levels of 2FA configuration:
+To use 2FA, you need a mobile device (or desktop application) with the correct time and date, and a TOTP-compatible authenticator app installed.
 
-1. **Global 2FA settings** enable 2FA system-wide and configure options such as the time window and SSH authentication requirements.
-2. **Per-user 2FA secrets** allow individual users to set up their own 2FA secrets using an authenticator app.
+TrueNAS uses the TOTP (Time-based One-Time Password) standard (RFC 6238), which is compatible with most authenticator apps. Popular options include:
 
-When global 2FA is enabled, it impacts services differently based on whether individual users configured their 2FA secrets:
+- **Microsoft Authenticator** (iOS, Android)
+- **Google Authenticator** (iOS, Android)
+- **Authy** (iOS, Android, desktop)
+- **Bitwarden** (cross-platform, open source)
+- **1Password** (cross-platform)
 
-* **UI/API authentication:**
-  * Users with a configured 2FA secret must provide the 2FA code to log in.
-  * Users without a configured 2FA secret can log in without 2FA but are prompted once per session to set it up. Users can skip this setup.
-* **SSH authentication:** If both global 2FA and SSH 2FA options are enabled, users with configured 2FA secrets must provide the code for password-based SSH access. Key-based authentication is not affected.
-
-{{< hint type=note >}}
-In GPOS STIG compatibility mode, 2FA for UI access is mandatory for all users.
-{{< /hint >}}
-
-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.
+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.
@@ -66,20 +58,20 @@ Internet access on the TrueNAS system is not required to use 2FA.
 
 2FA requires an app to generate the 2FA code.
 
-If a user configured a 2FA secret and the 2FA code is not working or the user cannot access it, the system is inaccessible to that user through the UI and SSH (if SSH 2FA is enabled).
-Users can [remove their 2FA secret](#removing-user-2fa-secrets) to regain access, or administrators can bypass or [disable global 2FA](#disabling-or-bypassing-2fa) using the CLI.
+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-global-2fa) using the CLI.
 
-## Enabling 2FA
+## Enabling Global 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. Select **Enable Two Factor Authentication Globally**, then click **Save**.
 
@@ -88,77 +80,138 @@ Before you begin, download Google Authenticator to your mobile device.
    If you want to enable two-factor authentication for SSH logins, select **Enable Two-Factor Auth for SSH** before you click **Save**.
    SSH 2FA only applies to users who configured a 2FA secret and are using password-based authentication.
 
-   TrueNAS takes you to the **Two-Factor Authentication** screen to set up your 2FA secret.
+   {{< 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 >}}
+
+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**.
+
+Select **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.
 
-   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.
+**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.
+   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. 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.
-   To generate a new QR code, click **Renew 2FA Secret**.
+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.
 
-   {{< hint type=info >}}
-   You can click **Skip Setup** if you want to set up 2FA later. Users without a configured 2FA secret can log in without providing a 2FA code.
-   {{< /hint >}}
+Your 2FA is now configured. You need to enter codes from your authenticator app when logging in.
 
-When **Global 2FA** is enabled, user accounts without configured 2FA secrets are prompted once per session after login to set up 2FA for their account.
-Users can skip this setup and proceed without 2FA. However, users who configured a 2FA secret must provide the 2FA code to log in.
+If you prefer not to set up 2FA at this time, see [Skipping 2FA Setup](#skipping-2fa-setup).
 
-### Disabling or Bypassing 2FA
+### Skipping 2FA Setup
 
-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**.
+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.
 
-### Removing User 2FA Secrets
+To skip the setup:
 
-Users can remove their configured 2FA secret at any time. This allows them to log in without providing a 2FA code.
+1. When the **Two-Factor Authentication** setup screen appears, click **Skip Setup**.
+2. Confirm the decision in the dialog that appears.
 
-1. Click the **Settings** icon on the top toolbar and select **Two-Factor Authentication** to open the **User Two-Factor Authentication Actions** screen.
+{{< 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 >}}
 
-2. Click **Unset 2FA Secret** and confirm the action.
+The setup prompt appears once per login session. If you skip setup, you are prompted again on your next login until you configure 2FA.
 
-After removing the 2FA secret, the user can log in without 2FA and can set up a new secret later if desired.
+### Removing Individual 2FA Configuration
 
-### Reactivating 2FA
+Users can remove their personal 2FA configuration without disabling 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**.
+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.
 
-Select **Enable Two Factor Authentication Globally**, then click **Save**.
-To change the system-generated **Secret**, click the **Settings** icon on the top toolbar and select **Two-Factor Authentication**.
-Click **Renew 2FA Secret**.
+{{< 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
 
-If a user configured a 2FA secret, the login screen adds another field for the randomized authenticator code. If this field is not immediately visible, try refreshing the browser.
+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.
-
-Users who have not configured a 2FA secret can log in with just their username and password.
+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
 
-SSH 2FA only applies to users who configured a 2FA secret and are using password-based authentication. Key-based SSH authentication is not affected by 2FA settings.
-
 1. Confirm that you set **Enable Two-Factor Auth for SSH** in **System > Advanced > Global Two Factor Authentication**.
 
 2. Ensure the user configured a 2FA secret (see [Enabling 2FA](#enabling-2fa) above).
@@ -167,7 +220,7 @@ SSH 2FA only applies to users who configured a 2FA secret and are using password
 
 4. 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.
 
-5. Open the Google Authentication app on your mobile device.
+4. Open your authenticator app on your mobile device or desktop.
 
 6. 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.
 

@@ -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 >}}
+Only clear 2FA for a user when it is 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.