TrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Managing Global 2FA (Two-Factor Authentication)

5 minute read.

Last Modified 2024-11-15 16:32 EST

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.

Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.

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 and QR codes generated in TrueNAS are compatible with your particular app before permanently activating 2FA.

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

What is 2FA and why should I enable it?

2FA adds an extra layer of security to your system to prevent someone from logging in, even if they have your password. 2FA requires you to verify your identity using a randomized six-digit code that regenerates every 30 seconds (unless modified) to use when you log in.

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

Enabling 2FA

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

Before you begin, download Google Authenticator to your mobile device.

Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Config.
Figure 1: 1 - Global Two Factor Authentication Settings Widget
Check Enable Two Factor Authentication Globally, then click Save.
Figure 2: 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.
You can also access the two-factor authentication settings for the currently logged-in user from the Settings option on the top toolbar. Click on the Settings icon, then select Two-Factor Authentication to open the User Two-Factor Authentication Actions screen.
Figure 3: User Two-Factor Authentication Actions Screen
Click Configure 2FA Secret to view the QR code.
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.
When using Google Authenticator, set Interval to 30 or the authenticator code might not function when logging in.
Click Configure 2FA Secret to open the User Two-Factor Authentication Actions screen where you scan the QR code using Google Authenticator. To generate a new QR code click Renew 2FA Secret.
After scanning the code click CLOSE to close the dialog on the Two-Factor Authentication screen.

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.

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.

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.

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.

Using 2FA to Log in to TrueNAS

Enabling 2FA changes the log in 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.

2FA Signin Splash Screen — Figure 4: 2FA Splash Screen

If you wait too long, a new number code displays in Google Authenticator, so you can retry.

Logging In Using SSH

Confirm that you set Enable Two-Factor Auth for SSH in System > Advanced > Global Two Factor Authentication.
Go to System > Services and edit the SSH service.
a. Set Log in as Admin with Password, then click Save.
b. Click the SSH toggle and wait for the service status to show that it is running.
Open the Google Authentication app on your mobile device.
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.