Two-Factor Sign-In
Ask your users for a code from an authenticator app after their password, magic link, email code or Google and Discord sign-in — optional for those who want it, or required for everyone.
Two-factor sign-in asks your users for a six-digit code from an authenticator app — Google Authenticator, 1Password, Authy or any other TOTP app — after they have signed in the usual way. It is included in the Pro and Enterprise plans, and you set it per app on the app's Two-Factor page in the dashboard.
Choosing who is asked
| Setting | What happens |
|---|---|
| Off | Nobody is asked for a code. |
| Optional | Users who turned two-factor on in the account widget are asked for a code at every sign-in. Everyone else signs in as before. |
| Required | Everyone is asked. A user with no authenticator sets one up as part of their next sign-in, before they get a session. |
The code is asked for after every way of signing in to your app: password, magic link, email code, Google and Discord. Single sign-on is the exception — your identity provider asks for its own second factor.
With Optional, users need somewhere to turn it on: add the Two-factor section on the app's Account Widget page. The Two-Factor page warns you when it is missing.
Turning two-factor off keeps the authenticators your users set up, so turning it back on asks them again without anyone having to re-scan. On the free plan the setting is kept but has no effect.
What your users see
When a sign-in needs a code, the widget shows a code screen instead of signing the user in. Nothing reaches your page until the code is right: the authframe:auth-success message arrives exactly as before, just one step later.
When a user has to set an authenticator up, the widget shows a QR code and the key to type in by hand. Once their app shows a code and they enter it, they are given ten recovery codes, once, and then signed in.
Google, Discord and magic-link sign-ins end in a popup or a tab. There the code is asked for on that page, and the session is handed over afterwards — to the widget, or to your success redirect — in the usual way.
Recovery codes and lost phones
Each recovery code signs a user in once, in place of an authenticator code. Users can replace them, or turn two-factor off (unless your app requires it), from the account widget, after entering a current code.
A user who lost both their phone and their recovery codes can be reset by anyone with the users:manage permission: on the app's Users page, users with two-factor carry a Two-factor badge and a Reset two-factor button. On an app that requires two-factor, they set a new authenticator up at their next sign-in.
Security details
- Codes follow RFC 6238: HMAC-SHA1, six digits, thirty-second steps, accepted one step either side of now for clock drift. Each code works once.
- The authenticator secret is stored encrypted, and recovery codes only as hashes. Neither is ever shown again, nor included in data exports.
- A sign-in waiting for its code lasts ten minutes and takes five wrong codes; after that the user signs in again. Codes are also rate limited per address and per account.
- Setting an authenticator up from the account widget asks for the user's password first, if they have one, so an unattended session cannot be used to lock its owner out.
- Turning two-factor on or off, a reset by a dashboard user and new recovery codes are recorded in your audit log. Your webhooks receive
user.updatedwith"changes": ["two_factor"]when a user turns it on or off.