Set up administrator two-factor authentication

With two-factor authentication on, an administrator account needs the 6-digit code from an authenticator app in addition to the password to sign in. Even if the password leaks, nobody can sign in without the device that holds the authenticator app. This page explains how administrators set up two-factor authentication on their own account, how to handle recovery codes, and how to require two-factor authentication for every administrator.

Before you begin

• Two-factor authentication is available for administrator accounts only. It is not shown for regular user accounts.
• You need a phone with a TOTP authenticator app installed, such as Google Authenticator or Microsoft Authenticator.
• You re-enter your current password during setup.
• To turn on the Require two-factor authentication for administrators policy, an administrator with permission to manage security settings must first set up two-factor authentication on their own account.

Open the two-factor authentication screen

The two-factor authentication screen is /manages/account/mfa on the administrator page. You can open it from any of the following places.

• Two-factor authentication in the user menu at the top right of the administrator page
• Open setup in the Administrator two-factor authentication card under Security Management > Security Settings
• My two-factor settings after opening your own account under User Management > Users
• Set up or Manage in the Two-factor authentication item of the workspace account settings

The Authenticator app panel on the screen shows the current status as On or Off.

Set up two-factor authentication

1. Select Set up in the Authenticator app panel.
2. Under Confirm it's you, enter your Current password and select Next.
3. Scan the QR code shown under Add to authenticator app with your authenticator app. If you cannot scan the QR code, select Copy key and enter the key in the authenticator app manually.
4. Enter the 6-digit code shown in the authenticator app and select Verify. You must confirm within the time shown on the screen; after it passes, start over from the beginning.
5. 10 Recovery codes are shown. Keep them somewhere safe with Copy or Save as file.
6. Check I saved my recovery codes somewhere safe and select Done.

The panel status changes to On and shows the date it was turned on. From the next sign-in, you are asked for an authentication code after the password.

Sign in with two-factor authentication

1. Enter your ID and password on the sign-in screen.
2. On the Two-factor authentication screen, enter the 6-digit Authentication code shown in the authenticator app and select Verify.
3. If you cannot use the authenticator app, select Use a recovery code and enter one of the saved codes in Recovery code. A recovery code cannot be used again once used.

A wrong code counts as a failed sign-in, the same as a wrong password. After several wrong attempts, sign-in is blocked for a while according to the login protection rules in Security Settings. If you stay on the authentication screen too long, the authentication step expires and you have to sign in again from the beginning.

When you are running low on recovery codes, a notice appears on the two-factor authentication screen. See Generate new recovery codes.

Generate new recovery codes

1. Select Generate new under Recovery codes on the two-factor authentication screen.
2. Enter the 6-digit code from the authenticator app and select Generate. A recovery code cannot be used for this step.
3. Save the 10 new recovery codes and select Done.

Generating new codes makes all previous recovery codes unusable. Replace the old codes you have kept with the new ones.

Turn off two-factor authentication

1. Select Turn off in the Authenticator app panel.
2. Enter your Current password together with the 6-digit code from the authenticator app or one recovery code, and select Turn off.

Once off, you can sign in with your password only, and all saved recovery codes become invalid. If the Require two-factor authentication for administrators policy is on, you must set it up again right after turning it off before you can use other features.

Require two-factor authentication for all administrators

1. First set up two-factor authentication on your own account. You cannot turn on the policy before you have set it up.
2. Expand the Administrator two-factor authentication card under Security Management > Security Settings.
3. Turn on Require two-factor authentication for administrators.
4. Select Save in the top-right corner and confirm.

When the policy is on, it works as follows.

The default is off. Before turning on the policy, tell your administrators how to set it up.

Reset another administrator's two-factor authentication

If an administrator has lost both the authenticator app and the recovery codes, a superuser can reset two-factor authentication for that account.

1. Select the administrator under User Management > Users.
2. Select Reset two-factor authentication in the Two-factor authentication item.
3. Read the confirmation dialog and select Reset.

Resetting removes the account's authenticator app registration and recovery codes and ends all of its signed-in sessions. The next sign-in uses the password only; if the required policy is on, the user must set it up again after signing in. You cannot reset your own account this way; use Turn off two-factor authentication instead.

Recover when every administrator is locked out

If no administrator can pass two-factor authentication, an operator with access to the server resets it from the terminal. Like the other user management commands, run it with the server stopped; it asks for the console access password.

~/setfn-spacebuilder user mfa reset <username>

For the requirements and how to stop the server, see Managing the Server from the Command Line.

Good to Know

• Setting up or turning off two-factor authentication, regenerating recovery codes, and resetting another administrator's two-factor authentication are all recorded in the Auth scope of the audit log. See Checking the Audit Log.
• Setting up or turning off two-factor authentication ends all other signed-in sessions of that account, and changing the password invalidates a two-factor sign-in step that is in progress.
• Setting up or turning off two-factor authentication, or generating new recovery codes, also disconnects AI tools connected through the sign-in and consent screen (MCP OAuth connections), so connect again from the AI tool.
• The encryption key that protects two-factor authentication data is stored in secrets/admin-mfa/ under the server configuration folder. Back up this folder together with the server. If a restored server does not have this key, two-factor verification fails for every administrator, so reset each administrator's two-factor authentication from the command line and set it up again.
• Restarting the server discards the two-factor step of any sign-in in progress, so sign in again from the beginning.

Related Documents

• Security Settings
• Checking the Audit Log
• Configure Account & Security policies
• Managing the Server from the Command Line