> Updated for version 6.0.30

Two-factor authentication adds a second step to signing in: after your password, you type a 6-digit code shown by an authenticator app on your phone. Even if someone knows your password, they cannot get in without your phone. This article explains how to turn it on and off, and what to do if you lose your phone.

![Your Profile window, Security tab: Two-factor authentication section turned off, with the blue Turn on two-factor authentication button](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBb2NKIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--8b448e914f03171144ba09786dbbb2465f398f5d/user--user-settings-security.en.png)
*the "Two-factor authentication" section of the "Your Profile" window, "Security" tab, with the "Turn on two-factor authentication" button*

## Where to find two-factor authentication

On the home screen, click your profile picture at the top right (its tooltip reads "Open your profile") to open the "Your Profile" window, then click the **Security** tab. The **Two-factor authentication** section shows whether the protection is on or off.

> 🔺 **Note:** the **Security** tab does not appear on self-hosted servers that sign users in without a password.

## Before you start

You need an authenticator app on your phone, for example Google Authenticator, Microsoft Authenticator, Aegis or 2FAS. It shows a 6-digit code that changes every 30 seconds. You also need your account password.

## Turn on two-factor authentication

1. In the **Security** tab, click **Turn on two-factor authentication**.
2. Type your account password, then click **Continue**.
3. In your app, add an account by scanning the QR code.
4. If you cannot scan, type the **Setup key** into the app by hand (the **Copy the key** button copies it).
5. Type the 6-digit code the app shows right now.
6. Click **Turn on**.

![Two-factor setup screen: numbered steps, QR code, setup key with Copy key and the 6-digit code field](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBb2dKIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--fc4198b9b866a27781138deda3694ca59a1c6d78/user--user-settings-security-enroll-qr.en.png)
*the setup screen, with the QR code, the setup key and the "6-digit code" field*

Your other devices are then signed out: you will have to sign in again there with your password and a code. The device you are using stays signed in.

## Keep your recovery codes

As soon as it is turned on, Celestory shows **10 recovery codes** (in the form `ABCDE-FGHJK`). If you lose your phone, each one lets you sign in instead of the app code. Each code works only once.

The codes are shown only once, and closing the page makes them disappear. Use **Copy** or **Download** (the file is called "Celestory recovery codes" and contains your email and the date), then keep them somewhere safe: a password manager, a safe, a piece of paper put away. Tick **I have kept my codes** to be able to click **Done**.

![Two-factor authentication is on: list of 10 recovery codes, Copy and Download buttons, I have kept my codes checkbox and Done button](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBb2tKIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--f2d6bb466f426e41b1d20a5d072ece47b7766008/user--user-settings-security-recovery-codes.en.png)
*the "Two-factor authentication is on" screen with the list of codes, the Copy and Download buttons, and the "I have kept my codes" checkbox*

### See how many codes are left

In the **Security** tab, Celestory shows "You have N recovery codes left". When you have 2 or fewer left, it suggests generating new ones before you run out.

### Generate new codes

1. Click **Generate new recovery codes**.
2. Type your password and a code (the app code, or a recovery code).
3. Click **Generate**.

The old codes stop working. Your other devices are signed out, as when you turned it on.

## Sign in with a code

1. Type your email and password as usual.
2. A screen asks "Enter the code from your authenticator app". Type the **6-digit code** shown by the app.
3. Click **Confirm**.

![Sign-in screen, second step: 6-digit code field, Use a recovery code link and Confirm button](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBb29KIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--bedf788710740714f7fc7daaf7387a83871b69ea/user--signin-mfa-code.en.png)
*the sign-in screen asking for the 6-digit code, with the "Use a recovery code" link*

A code works only once: if you have just used the code on screen, wait for the next one (30 seconds at most) before a second operation.

### With a recovery code

Click **Use a recovery code** and type one of your codes. Capital letters and the dash do not matter. To go back to the app code, click **Use the code from the authenticator app**. The **Back to email and password** link takes you back to the first step.

## Turn off two-factor authentication

1. In the **Security** tab, click **Turn off two-factor authentication**.
2. Type your password and a code (app code or recovery code).
3. Click **Turn off**.

Your account is then protected by your password only. Your other devices are signed out. If you turn it on again later, you start a full setup again, with a new key and new recovery codes.

## Attempt limits and lockouts

To stop anyone from guessing a code, Celestory limits attempts.

| Situation | What happens |
| --- | --- |
| 5 wrong codes during one sign-in | The verification stops: type your email and password again |
| You wait more than 5 minutes on the code screen | The verification expires, same thing |
| 10 failures in a row (codes, or password when turning on, turning off or regenerating codes) | The account is locked for 15 minutes |

During a lockout, signing in is refused even with the right password, and a message says how long to wait. A success resets the counter, and so does the end of a lockout.

> 🔺 **Note:** if you reset your password, two-factor authentication stays on, but all your sessions are signed out.

## Troubleshooting

| Message | Solution |
| --- | --- |
| Wrong code | Wait for the app to show a new code and try again. Check that your phone's clock is set automatically |
| The verification has expired | Type your email and password again |
| Account temporarily locked | Try again after the delay shown |
| Wrong password | Check it; otherwise sign out and use "Forgot password" |
| Two-factor authentication is not available | The server is not configured: see the box below |
| The setup is no longer in progress | Click **Cancel**, then **Turn on two-factor authentication** again |

For an error you cannot fix alone, Celestory offers copyable details to send to support (they contain no password or code). See [Understanding an error message](https://documentation.celestory.io/hc/celestorydoc/articles/1795347834-understanding-an-error-message).

## For administrators of self-hosted servers

> ⚠ **Warning:** two-factor secrets are encrypted with a key that you give to the authentication server, in the `MFA_ENCRYPTION_KEY` variable (32 random bytes, as 64 hexadecimal characters or as base64, for example with `openssl rand -hex 32`). Without this key, nobody can turn on two-factor authentication, **and accounts that already turned it on can no longer sign in**: the second step is never skipped. Losing or changing the key makes every stored secret unreadable, so keep it like a backup secret. The optional `MFA_ISSUER` variable sets the name shown by the authenticator app ("Celestory" by default).

## See also

- [Understanding an error message](https://documentation.celestory.io/hc/celestorydoc/articles/1795347834-understanding-an-error-message)
