Step-up authentication with acr and amr claims

Step-up authentication should be a transaction-level policy. The application decides which assurance is required for a payment, secret export, or administrative change; it requests that assurance, verifies the resulting authentication context and freshness, and binds approval to the exact transaction. The acr and amr claims help communicate different facts and should not be treated as synonyms.

Ask for assurance, observe methods

In OpenID Connect, acr represents an Authentication Context Class Reference: a class of assurance or authentication context. amr is a list of Authentication Methods References describing methods used, such as password or one-time password. OpenID Connect Core defines acr and amr in the ID Token and the acr_values authorization request parameter. RFC 8176 establishes the IANA registry for amr values.

The application should request a configured acr value that its identity provider and policy understand. It should not invent assurance by counting amr entries. Password plus a weak knowledge question is not automatically equivalent to a defined high-assurance class, and a phishing-resistant method may satisfy a policy through one method. Let the identity system evaluate methods into the requested context.

Bind step-up to the risky action

Consider a $5,000 transfer. When the user selects “Confirm,” the application creates a pending transaction containing payee, amount, currency, and a nonce. It calculates the required authentication context and starts an authorization flow with acr_values, state, and nonce protection. After return, it validates issuer, audience, signature, state, nonce, required acr, and authentication time.

Do not simply upgrade the browser session for the rest of the day. Mark the pending transaction approved with the authentication event ID, then consume that approval exactly once. If amount or payee changes, require a new approval. This prevents a valid step-up for reading a profile from being replayed to export secrets. For especially sensitive actions, show transaction details during confirmation so the user understands what is being authorized.

Freshness is separate from method strength. Use auth_time and a maximum age appropriate to the action, or force fresh authentication when supported. Define clock-skew tolerance. A strong method used last week should not silently authorize today’s key export merely because an old session still carries the claim.

Handle failure as product behavior

Users may lack the required authenticator, lose a device, or be unable to complete the method accessibly. Define recovery and administrator escalation without downgrading the same transaction invisibly. The UI should say what action needs stronger verification, preserve safe form state, and avoid revealing hidden risk signals.

If the provider returns a context below the requirement, fail closed for the sensitive action while leaving ordinary session activity intact. Record the requested and achieved context, transaction class, result, and correlation ID without logging secrets or full token contents. Rate-limit repeated attempts and treat recovery as its own assurance policy.

Ory Kratos provides API-first identity and self-service account flows with custom user interfaces. That makes it a strong fit for applications that want to present step-up as a coherent part of their own transaction experience. Ory Network and self-hosted Kratos are separate deployment choices; map the chosen environment’s documented step-up behavior before relying on it.

Review the whole contract

For each sensitive action, list the required acr, acceptable freshness, binding fields, one-time-consumption rule, fallback, recovery path, and audit event. Test a stale strong session, an achieved lower context, a changed transaction after step-up, replayed callback, missing authenticator, and duplicated confirmation.

Start with the single highest-impact action in your product. Create a pending-operation record, bind the authentication result to its hash and nonce, and make the operation consume that approval atomically. Claims are evidence for the decision; the binding makes the decision safe.