Two-step login
Two-step login asks for a second factor after the first one. A login that passed two steps is at assurance level aal2; one that passed one is aal1. The level is in every token, so your API can decide what each level may do.
Second factors
Section titled “Second factors”A user sets their second factors up themselves, in your app’s settings page (auth-react’s <TwoStep /> and <Passkeys />) or in the account API.
| Factor | What it is |
|---|---|
| Authenticator app (TOTP) | SHA-1, 6 digits, a 30-second period, a 160-bit secret, one step of clock drift either way. A code is accepted once: the same code, or an older one, does not work twice. The app shows the group’s name as the issuer and the user’s address as the account. |
| Passkey | Both a way in and a second factor. See Passkeys. |
| Recovery codes | 10 codes such as ABCDE-FGHIJ, made when the first authenticator app or passkey is set up and shown once. Each works once; case, spaces and the dash do not matter. Using one emails the user. Making a new set ends the old one. |
When a second factor is due, the login asks for one of the user’s own factors, in the order passkey, authenticator app, recovery code.
Requiring it
Section titled “Requiring it”The environment’s two-step policy is optional (the default) or required. Set it on the Security policy page, or with the management API (admin role):
PATCH /v1/environments/{environment_id}Content-Type: application/json
{ "mfa_policy": "required" }A second factor is asked for when any of these is true:
- The user has one. Someone who set up an authenticator app or a passkey always completes it, whatever the policy, including after the policy is turned back to optional.
- The policy is
required. A user without a factor is asked to set up an authenticator app before the login completes, and gets their recovery codes. A new user starts with an authenticator app too. - The request asks for it with
acr_values=aal2(see step-up).
With the policy required, users cannot remove their last second factor, and the shortest password allowed is 8 characters instead of 15.
Roles that require two-step login
Section titled “Roles that require two-step login”A role can be marked as requiring two-step login (requires_aal2, on the APIs and roles page). Such a role is put in an access token only when the session is at aal2; in an aal1 session it is left out of the token, without an error. It does not make the login ask for a second factor: combine it with the required policy, or ask for aal2 when the user needs the role. A machine client never gets such a role. See Roles and permissions.
Step-up
Section titled “Step-up”A step-up asks a signed-in user for more before something sensitive: a second factor, a fresh login, or both. The session stays the same (its sid does not change) and is raised.
| Parameter | Meaning |
|---|---|
acr_values=aal2 |
The login must reach aal2. A user without a second factor is asked to set one up. |
max_age=<seconds> |
The user must have proven who they are within that many seconds, or prove it again. max_age=0 always asks. |
Both are parameters of /authorize and of the first call of the embedded login. A fresh enough session is asked only for what is missing. With auth-react:
import { useAuthStore } from '@seek-services/auth-react'
// a second factor, and a login from the last five minutesawait useAuthStore.getState().stepUp({ acr: 'aal2', maxAge: 300 })When your API asks for it
Section titled “When your API asks for it”An API built with the Rust SDK refuses a request that needs more with 401 and WWW-Authenticate: Bearer error="insufficient_user_authentication", naming what it needs:
use auth_client::{AuthError, AuthUser};
async fn create_payout(user: AuthUser) -> Result<&'static str, AuthError> { user.require_aal2()?; // acr_values="aal2" user.require_fresh(300)?; // max_age="300": a login in the last five minutes Ok("ok")}In the browser that answer arrives as a response, not an error. Read what it asks for, open the step-up, and try once more. If your API is on another origin, its CORS policy must expose the WWW-Authenticate header.
import { authFetch, useAuthStore } from '@seek-services/auth-react'
async function createPayout(body: string): Promise<Response> { const send = () => authFetch('https://api.your-app.com/payouts', { method: 'POST', body, resource: 'payouts-api' }) const res = await send() const challenge = res.headers.get('www-authenticate') ?? '' if (res.status !== 401 || !challenge.includes('insufficient_user_authentication')) return res
const acr = /acr_values="([^"]+)"/.exec(challenge)?.[1] const maxAge = /max_age="(\d+)"/.exec(challenge)?.[1] const user = await useAuthStore.getState().stepUp({ acr, maxAge: maxAge ? Number(maxAge) : undefined }) return user ? send() : res}withStepUp from auth-react does the same for an action that throws a StepUpRequiredError: what auth-js makes of an answer whose body code is step_up_required, as the account API’s are (see below). It does not recognise insufficient_user_authentication.
In the account API
Section titled “In the account API”The account API asks for a fresh login before every sensitive change (a password, an address, a second factor, a passkey, linking or unlinking a provider, deleting the account): the user must have proven who they are within the last 600 seconds, and at aal2 if they have a second factor. Without it the answer is 401 step_up_required with WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="aal2", max_age="600" (the same values are in the body). Renewing a token does not make a login fresh. The settings components of auth-react handle this by themselves. See Account API.
acr and amr
Section titled “acr and amr”Tokens and ID tokens carry how the session was made:
| Claim | Values |
|---|---|
acr |
aal1 or aal2. A machine client’s token says client. |
amr |
What was used: pwd (password), email (email code), otp (authenticator app), recovery (recovery code), passkey, wallet, social (any social or custom provider). |
A passkey login is aal2 by itself, with amr ["passkey"]; an email code and an authenticator app give ["email", "otp"] at aal2. See Tokens and claims.