Install
Configure
twoFactorEnabled, a read-only checkbox that carries the account section, and three hidden fields for the encrypted secret, the hashed recovery codes and the last accepted time step. Run frogbot generate:importmap after adding the plugin in build-only workflows; frogbot dev does it for you.
Turn it on
Each user turns two-factor sign-in on from the Two-factor sign-in section of their own account:- Turn on shows a QR code and the key as text. The user scans it with an authenticator app (1Password, Google Authenticator, Authy and others) and types the 6-digit code it shows.
- FrogBot shows 10 recovery codes once, with Copy and Download. Each one signs in once when the authenticator is lost.
- Every other session of that user ends; the current one stays. With
auth.useSessions: falsethere are no sessions to end, and tokens already issued stay valid until they expire.
Require it
require returns true for users who must have two-factor sign-in.
- A required user without it is sent to setup at their next sign-in, before any session exists.
- A required user can’t turn it off. The account section hides Turn off, and the API refuses with
403. - When
requirestops returning true for a user, they can turn it off with a code. This happens, for example, when an admin turns a workspace’s requirement off andrequirereads that setting.
require covers the first user, POST /api/<collection>/first-register creates the account and answers the same 202 as password login instead of signing them in. The admin’s create-first-user form doesn’t follow that answer, so after registering there, sign in with the new password to reach setup.
Sign-in flow
-
Sign-in methods. After the provider confirms the user, the plugin’s
beforeSignInhook pauses the sign-in and redirects to the code page at/api/<collection>/two-factor, which continues toreturnToonce the code is accepted. -
Password, admin. The plugin replaces the admin login view, unless your config sets
admin.components.views.login, with one that renders the same logo,beforeLogin, form andafterLogincomponents. A correct password for a user who needs a code goes to the code page, which continues into the admin. -
Password, API.
POST /api/<collection>/loginanswers202for a user who needs a code, with no token and a short-lived, HttpOnly cookie scoped to the code endpoints:twoFactoris'setup'for a required user without it. Send the code toPOST <url>/verifywith that cookie as{ "code": "123456" }to get the normal login response, token included. AddreturnTo(a path on your server) to the login body and the code page continues there instead. -
Reset password. For a user with two-factor sign-in on or required, the new password is saved and every session ends, but nobody is signed in: REST answers
{ message, twoFactor: 'signIn' }, GraphQL and the Local API return no token, and the person signs in with the new password and a code.
refresh-token refuse it.
Reset
A user who loses both their authenticator and their recovery codes needs an admin. WhencanReset allows it, another user’s document shows Reset two-factor sign-in. A reset does this:
- It removes their secret and recovery codes.
- It ends every session. With
auth.useSessions: false, issued tokens stay valid until they expire. - It clears the code lock.
canReset is asked only for a user that the admin can read and update under the collection’s access rules. Nobody can reset their own. A still-required user is sent to setup at their next sign-in.
Endpoints
All live under/api/<collection> and answer errors as { errors: [{ message }] }. A refused code, here and on /two-factor/verify and /two-factor/setup, also carries data.code, so a client branches on that rather than the message:
The first four act on the signed-in user.
hasTwoFactor(user) tells whether a user has it on.
Emails
The plugin emails the user through your email adapter when two-factor sign-in is turned on or off, a recovery code is used, new codes are created, and an admin resets it. Replace one withemails.<event> returning { subject, text, html? }, or turn it off with false. A failed send is logged and never fails the request.
Limits
- GraphQL
loginUserand the Local APIlogindon’t have a code step, so they fail for users who need a code or setup. Use the REST login. canResetdefaults to nobody, so without it a user who loses their authenticator and recovery codes can’t get back in.- Another
beforeSignInhook that pauses sign-in, such as a terms step, can’t be combined with two-factor sign-in. When it resumes withfinishSignInfor a user who needs a code, the sign-in is refused with403rather than skip the code. - Passkeys, security keys and per-tenant two-factor settings aren’t supported.