Skip to content

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.

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.

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.

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.

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 minutes
await useAuthStore.getState().stepUp({ acr: 'aal2', maxAge: 300 })

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.

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.

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.