Managing Global 2FA (Two-Factor Authentication)

Global Two-factor authentication (2FA) is great for increasing security.

TrueNAS offers global 2FA to ensure that entities cannot use a compromised administrator or root password to access the administrator interface.

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.

Two-factor authentication is time-based and requires a correct system time setting. We strongly recommend ensuring Network Time Protocol (NTP) is functional before enabling two-factor authentication!

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.

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 using the CLI.

Set up a second 2FA device as a backup before proceeding.

Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See About TrueNAS 2FA for recommended options.

1. Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Configure.

   

2. Check Enable Two Factor Authentication Globally, then click Save.

   

   If you want to enable two-factor authentication for SSH logins, select Enable Two-Factor Auth for SSH before you click Save.

   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.

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 for detailed instructions on configuring 2FA for individual user accounts.

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 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.

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.

Set up a second 2FA device as a backup before proceeding.

Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See 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.

   

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.

   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.

   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.

   

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.

Your 2FA is now configured. You need to enter codes from your authenticator app when logging in.

If you prefer not to set up 2FA at this time, see Skipping 2FA Setup.

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 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.

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.

The setup prompt appears once per login session. If you skip setup, you are prompted again on your next login until you configure 2FA.

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.

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.

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

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.

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.

Enabling 2FA changes the login process for both the TrueNAS web interface and SSH logins.

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.

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.

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 Start Service button to start the service. Wait for the service status to show that it is running.

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.