Multi-factor authentication setup

Multi-factor authentication

MFA adds a second factor — a six-digit code from an authenticator app — on top of your password. Keystone supports any TOTP-compliant authenticator (Authy, 1Password, Google Authenticator, the password manager built into iOS / macOS, etc.). It’s required for admin accounts in production and recommended for everyone.

Turning MFA on

From the user menu (top-right) → Profile → Security.

1. Click Set up MFA. Keystone shows a QR code and a 32-character secret.
2. Open your authenticator app and scan the QR code (or paste the secret if your app doesn’t have a camera). The app immediately starts producing 6-digit codes that change every 30 seconds.
3. Type the current code from the app into the form on the Keystone page. This proves the device pairing worked.
4. Keystone shows you eight recovery codes. Save them somewhere safe — a password manager is ideal, a printed copy in a locked drawer also works. Each code works once.

After step 4, MFA is on. The next time you sign in (or after your session expires), Keystone will prompt for a 6-digit code from your authenticator before letting you continue.

When you lose your authenticator

If your phone breaks or you reset it:

1. Sign in with your password as usual.
2. On the MFA challenge screen, click Use a recovery code instead.
3. Type one of the eight codes you saved during setup.
4. Once you’re in, go straight to Profile → Security → Reset MFA to pair a new authenticator. The new pairing invalidates the lost device.

If you’ve also lost the recovery codes, ask an admin (anyone with identity::users::manage) to clear MFA on your account. They’ll need to verify your identity out-of-band first — the reset is logged.

Required for admins

Workspace admins and trust admins are required to have MFA enabled — they can sign in once without it but every subsequent request bounces to the setup page until MFA is on. This is enforced server-side by the RequireMfaForAdmins middleware; there’s no per-user opt-out.

SSO accounts

If you sign in via an external IdP (Microsoft Entra, Google Workspace, SAML), MFA is whatever the IdP enforces — Keystone trusts the IdP’s assertion and doesn’t add a second prompt. Your IdP admin manages MFA policy in that case.