diff --git a/content/SCALE/SCALETutorials/Credentials/ManageUsers.md b/content/SCALE/SCALETutorials/Credentials/ManageUsers.md index 3eabd9dedd..1ba07533f7 100644 --- a/content/SCALE/SCALETutorials/Credentials/ManageUsers.md +++ b/content/SCALE/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" >}}). diff --git a/content/SCALE/SCALETutorials/SystemSettings/Advanced/ManageGlobal2FASCALE.md b/content/SCALE/SCALETutorials/SystemSettings/Advanced/ManageGlobal2FASCALE.md index 1976652f0c..48b394b58e 100644 --- a/content/SCALE/SCALETutorials/SystemSettings/Advanced/ManageGlobal2FASCALE.md +++ b/content/SCALE/SCALETutorials/SystemSettings/Advanced/ManageGlobal2FASCALE.md @@ -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,56 +80,121 @@ 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 @@ -145,20 +202,16 @@ Enabling 2FA changes the login process for both the TrueNAS web interface and SS ### 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** Start Service 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. diff --git a/content/SCALE/SCALEUIReference/Credentials/UsersScreen.md b/content/SCALE/SCALEUIReference/Credentials/UsersScreen.md index 755170cece..cc069a8b03 100644 --- a/content/SCALE/SCALEUIReference/Credentials/UsersScreen.md +++ b/content/SCALE/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 >}} +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. diff --git a/content/SCALE/SCALEUIReference/SystemSettings/AdvancedSettingsScreen.md b/content/SCALE/SCALEUIReference/SystemSettings/AdvancedSettingsScreen.md index 524ac63807..ff77f1fc72 100644 --- a/content/SCALE/SCALEUIReference/SystemSettings/AdvancedSettingsScreen.md +++ b/content/SCALE/SCALEUIReference/SystemSettings/AdvancedSettingsScreen.md @@ -475,8 +475,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 >}} diff --git a/content/SCALE/SCALEUIReference/TopToolbar/Settings/2FAScreenSCALE.md b/content/SCALE/SCALEUIReference/TopToolbar/Settings/2FAScreenSCALE.md index 8a4cf8e19a..e530c65c3b 100644 --- a/content/SCALE/SCALEUIReference/TopToolbar/Settings/2FAScreenSCALE.md +++ b/content/SCALE/SCALEUIReference/TopToolbar/Settings/2FAScreenSCALE.md @@ -13,25 +13,23 @@ tags: Two-factor authentication is time-based and requires a correct system time setting. {{< /hint >}} -The **Two-Factor Authentication** screen, accessed from the **Settings** menu on the top toolbar, displays user-level two-factor authentication (2FA) settings. The screen shows a different message if 2FA is enabled than when not configured or disabled. +The **Two-Factor Authentication** screen, accessed from the **Settings** menu on the top toolbar, allows managing user-level two-factor authentication (2FA) credentials. This option only appears in the Settings menu when an administrator has enabled Global 2FA. -This screen allows users to configure, renew, or remove their individual 2FA secrets. - -Global 2FA settings are configured on the [**Advanced Settings**]({{< ref "AdvancedSettingsScreen" >}}) screen. +Administrators can enable Global 2FA on the [**Advanced Settings**]({{< ref "AdvancedSettingsScreen" >}}) screen. For more information, see the [Managing Global 2FA]({{< ref "ManageGlobal2FASCALE" >}}) tutorial. -{{< trueimage src="/images/SCALE/Credentials/2FAScreenDisabled.png" alt="2FAScreenDisabled" id="2FA Screen with Disabled Message" >}} - {{< trueimage src="/images/SCALE/SystemSettings/2FAScreenEnabled.png" alt="2FAScreenEnabled" id="2FA Screen with Enabled Message" >}} ## Actions -**Configure 2FA Secret** opens the **Set Up Two-Factor Authentication** screen that displays a QR code and unique key for use with an authenticator app. The screen includes a **Skip Setup** button. - -**Renew Secret** changes the system-generated **Secret** and **Provisioning URI** values and generates a new QR code and unique key. +**Renew Secret** changes the system-generated **Secret** and **Provisioning URI** values. {{< trueimage src="/images/SCALE/Credentials/2FARenewSecretDialog.png" alt="2FA Renew Secret" id="Renew Secret Dialog" >}} -**Unset 2FA Secret** removes the configured 2FA secret. This action displays a confirmation dialog before proceeding. +**Unset 2FA Secret** removes the existing 2FA setup of the user. A confirmation dialog appears before removing the configuration. -{{< trueimage src="/images/SCALE/Credentials/Unset2FA.png" alt="2FA Unset Dialog" id="2FA Unset Dialog" >}} +{{< trueimage src="/images/SCALE/Credentials/Unset2FASecret.png" alt="Unset Two-Factor Authentication Dialog" id="Unset Two-Factor Authentication Dialog" >}} + +{{< hint type=warning >}} +Removing your 2FA configuration reduces account security. If global 2FA is enabled, you are prompted to set up 2FA again on your next login, though you can skip this prompt if needed. +{{< /hint >}} diff --git a/static/images/SCALE/Credentials/Clear2FADialog.png b/static/images/SCALE/Credentials/Clear2FADialog.png new file mode 100644 index 0000000000..9654f6a51e Binary files /dev/null and b/static/images/SCALE/Credentials/Clear2FADialog.png differ diff --git a/static/images/SCALE/Credentials/Unset2FASecret.png b/static/images/SCALE/Credentials/Unset2FASecret.png new file mode 100644 index 0000000000..f8b8b28d31 Binary files /dev/null and b/static/images/SCALE/Credentials/Unset2FASecret.png differ diff --git a/static/images/SCALE/SystemSettings/UserTwoFactorAuthenticationActionsScreen.png b/static/images/SCALE/SystemSettings/UserTwoFactorAuthenticationActionsScreen.png index ea0bd83c9b..b115917134 100644 Binary files a/static/images/SCALE/SystemSettings/UserTwoFactorAuthenticationActionsScreen.png and b/static/images/SCALE/SystemSettings/UserTwoFactorAuthenticationActionsScreen.png differ