Set up two-factor sign-in

Two-factor sign-in asks for a 6-digit code from an authenticator app after your password. Each person sets it up for their own account on My profile. Administrators and Owners may be required to do so. See Require two-factor sign-in.

Before you start

• Install an authenticator app that reads standard time-based codes, such as 1Password, Bitwarden, Google Authenticator or Authy.
• Make sure the clock on the phone or computer that runs the app is correct. A code from a clock that is off is rejected.
• Have a password manager ready for the backup codes.

Steps

Enroll

1. Open My profile in the sidebar, under Account.
2. In the Sign-in group, find Two-factor authentication. A badge shows off, or required when your role must use it. Click Set up 2FA.
3. The page now shows Set up two-factor authentication. Scan the QR code with the app. If you cannot scan, type the Secret (manual entry) into the app.
4. Copy the Backup codes into your password manager. There are ten. Each works once and signs you in when you do not have the authenticator. They are shown only on this screen.
5. In Code from your app, enter the 6-digit code the app shows, then click Turn on 2FA.

The page then shows “2FA enrolled successfully”. If you clicked Cancel or left the screen before step 5, two-factor stays off.

Sign in with a code

1. Enter your username and password as usual. The next screen is Two-factor authentication.
2. Type the 6-digit code from the app. Codes change every 30 seconds.
3. To use a backup code, click Use a backup code instead, type the code and click Verify backup code. Click Use authenticator code instead to switch back.
4. Tick Trust this device for 30 days before you submit if you do not want to be asked for a code on this browser for 30 days.

The screen stays valid for 5 minutes after the password is accepted. After that you sign in again from the start. A code that was already accepted cannot be used a second time.

Watch the backup codes

My profile shows how many backup codes are left. With two or fewer left it warns you. At none it reads “No backup codes left” and a lost authenticator locks you out. To get a fresh set, turn two-factor off and enroll again. The new enrollment has a new secret.

Turn two-factor off

Before you turn two-factor off

Sign-in then needs only your password. The secret and all remaining backup codes are deleted, so the authenticator entry and any saved codes stop working. To use two-factor again, enroll from the beginning. When two-factor sign-in is required, an Administrator or Owner is sent back to this page to enroll again at the next sign-in.

1. Open My profile. Under Two-factor authentication, type your password in Confirm your password.
2. Click Turn off 2FA and confirm Turn off 2FA in the dialog. The page shows “2FA disabled”.

Check that it worked

• My profile shows the badge on. The verdict line at the top reads “Account protected” followed by the number of devices, as long as at least three backup codes remain.
• Under Users, an Owner sees enrolled in the 2FA column for your row.
• Sign out and in again. The Two-factor authentication screen appears after your password.

If it fails

• “Code rejected — make sure your device clock is correct and the code is fresh”: on the enrollment screen, wait for the next code and enter it. Check the device time.
• “That code didn’t match. Check the digits — codes change every 30 seconds — or use a backup code.”: at sign-in, wait for the next code. Do not retype one that was already accepted.
• “That backup code didn’t match, or it was already used. Check it, or use your authenticator instead.”: each backup code works once. Try another.
• “Too many failed attempts from this address. Try again in N minutes.”: wait for the time shown.
• “This account is locked. Ask an administrator to unlock it.”: eight wrong codes in a row lock the account. An Owner unlocks it under Users, or on the master with sudo hctl user unlock <username>.
• You lost the authenticator and have no backup codes: ask an Owner to follow Regain access to the panel.
• “validation failed: current password is incorrect”: retype the password in Confirm your password.