An access token says the user signed in at some point, but not whether they used a passkey or a password, or whether that happened ten seconds or ten hours ago, and a payment or admin API often needs to know. RFC 9470, the OAuth 2.0 Step Up Authentication Challenge Protocol, gives resource servers a standard way to say "this token is not good enough for this call" and tells clients how to come back with one that is. It was published as a Proposed Standard in September 2023 by authors from Okta and Ping Identity. This guide explains the challenge, the client and authorisation server behaviour, the acr and auth_time claims, how to design authentication levels and freshness rules, and how vendor mechanisms such as Microsoft Entra authentication context compare. It is for API owners, identity engineers and architects who need transaction-level assurance without forcing strong authentication on every request.
Key takeaways
- The resource server decides, the authorisation server delivers: the API returns HTTP 401 with
error="insufficient_user_authentication"and the requiredacr_valuesormax_age, and the client sends the user back to the authorisation server with those parameters. - Two dimensions, not one:
acrdescribes how the user authenticated andauth_timewhen; most sensitive operations need both a strong method and a recent event. - The authorisation server should not fudge it: RFC 9470 says it should treat a requested
acras mandatory for access tokens and fail withunmet_authentication_requirementsrather than issue a token the API will reject. - Define levels as policy, not as a ladder: RFC 9470 calls "level" a metaphor; publish a small set of named
acrvalues with clear meaning, mapped to NIST SP 800-63B authenticator assurance levels where possible. - Step-up is an authentication signal, not authorisation: it proves a fresh, strong login, and the API must still check what the user is allowed to do.
The protocol in six steps
- The client calls the API with an access token.
- The resource server decides the token's authentication event does not meet the requirement for this operation and returns a challenge.
- The client redirects the user to the authorisation server with the requested
acr_valuesand/ormax_age. - The user authenticates as required and the authorisation server issues a new access token that records the authentication event.
- The client retries the call with the new token.
- The resource server validates the new
acrandauth_timeand serves the request.
The challenge extends the RFC 6750 Bearer scheme. The RFC's examples:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
error_description="A different authentication level is required",
acr_values="myACR"
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
error_description="More recent authentication is required",
max_age="5"
The client then sends an authorisation request such as ...&response_type=code&scope=purchase&acr_values=myACR. Both parameters come from OpenID Connect Core, where max_age forces the provider to attempt active re-authentication if the last login is older and to return auth_time.
Parameters, claims and errors at a glance
| Item | Where it appears | Meaning |
|---|---|---|
insufficient_user_authentication | RS challenge, HTTP 401 | The token's authentication event does not meet the resource's requirement |
acr_values | Challenge and authorisation request | Space-separated authentication context class references in order of preference; one must be met |
max_age | Challenge and authorisation request | Maximum seconds since the last active authentication (user interaction with the AS) |
acr | JWT access token (RFC 9068), introspection response | The authentication context class that was satisfied |
auth_time | JWT access token, introspection response | Time of the authentication event, in seconds since the Unix epoch |
amr | ID token (OIDC); values registered in RFC 8176 | Methods used, for example hwk, mfa, otp, pwd |
unmet_authentication_requirements | AS error response | The AS could not satisfy the requested acr |
acr_values_supported | AS metadata (RFC 8414) | Which acr values the AS can produce |
RFC 9470 section 6.1 notes that acr and auth_time are fixed at authentication time and do not change when a token is refreshed. A refresh token therefore cannot make a stale authentication look fresh, and the resource server must compare auth_time with its own freshness rule on every sensitive call. See the OAuth Refresh Token Rotation and Expiry Guide.
Designing authentication levels and freshness
RFC 9470 leaves the meaning of acr values to you. A small, documented set works better than vendor-specific strings scattered through code.
Example acr value | Definition | Rough NIST SP 800-63B equivalent | Typical operations |
|---|---|---|---|
urn:example:acr:basic | Password or single factor | AAL1 | Read profile, browse |
urn:example:acr:mfa | Two factors, any type | AAL2 | Change settings, view statements |
urn:example:acr:phr | Phishing-resistant: passkey or hardware key | AAL2 or AAL3 depending on authenticator | Add payee, export data, admin actions |
urn:example:acr:phr-hw | Hardware-bound, non-exportable key with user verification | AAL3 | Production admin, key release, large payments |
- Freshness by operation: combine
acrwithmax_age. For example, adding a payee might needphrwithin 300 seconds, while viewing statements needsmfawithin the session. - Anchor to NIST timeouts: SP 800-63B-4 says AAL2 sessions should re-authenticate within 24 hours overall and after 1 hour of inactivity, and AAL3 sessions within 12 hours (a "shall") and after 15 minutes of inactivity. Step-up rules for sensitive operations should be stricter than these session ceilings, not looser.
- Prefer URIs you own:
acrvalues are opaque strings. Namespaced URIs avoid collisions when you federate with partners. - Do not leak sensitivity: RFC 9470 warns that
acr_valuescan reveal that a resource or user is high value. Keep values generic.
See the Phishing-Resistant MFA Guide for the authenticators behind the top levels.
Worked example: adding a payee
A banking app holds a token from a password and SMS login two hours ago (acr of urn:example:acr:mfa). The user adds a new payee. The payments API rule for that operation is urn:example:acr:phr within 300 seconds, so the API returns 401 with acr_values="urn:example:acr:phr" and max_age="300". The app redirects to the authorisation server, the user approves with a passkey, and the new token carries acr of urn:example:acr:phr and a current auth_time. The app retries the call, the API accepts it, and the app keeps using its original token for balance and statement calls. Ten minutes later a second payee needs another step-up, because the freshness window has passed.
Responsibilities by component
| Component | Must do | Must not do |
|---|---|---|
| Resource server | Validate the token first; map each sensitive operation to acr and freshness; compare acr and auth_time; return the challenge with 401 | Treat step-up as permission; challenge before validating the token where that leaks requirements |
| Client | Parse the challenge, start a new authorisation request with the same parameters, retry once with the new token, keep separate tokens per assurance need | Inspect access token contents (RFC 9470 and RFC 9068 say clients must not); loop on repeated challenges |
| Authorisation server | Treat requested acr as mandatory for access tokens; include auth_time when max_age is used; advertise acr_values_supported | Silently issue a token at a lower level than requested |
Vendor mechanisms compared
- RFC 9470: standard
acr_valuesandmax_agein the Bearer challenge; works with any OpenID Connect provider that honours them. - Microsoft Entra ID authentication context: administrators define contexts
C1toC99and attach Conditional Access policies (for example MFA or a compliant device). The API checks theacrsclaim and, if the needed context is missing, returns 401 witherror="insufficient_claims", a base64claimsvalue such as{"access_token":{"acrs":{"essential":true,"value":"C1"}}}andcc_type="authcontext". The client passes the decoded claims to an interactive sign-in. It requires Entra ID P1, applies only to user sign-in, and context IDs should be read at runtime because they vary per tenant. - Design implication: keep the step-up decision in one policy layer in your API and translate it into either an RFC 9470 challenge or a vendor claims challenge, so switching identity providers does not mean rewriting every endpoint.
Where step-up fits in transaction security
- Payments: step-up proves the user, but European strong customer authentication also requires dynamic linking of the authentication to amount and payee. Pair step-up with Rich Authorization Requests so the consent carries the transaction details. See the PSD2/PSD3 Strong Customer Authentication Guide and the OAuth Rich Authorization Requests (RAR) Guide.
- Stolen sessions: an attacker replaying a stolen token or session cookie (MITRE ATT&CK T1550.001 Application Access Token, T1539 Steal Web Session Cookie) cannot complete a fresh phishing-resistant step-up, so step-up on high-risk calls limits what stolen sessions can do. Sender-constrained tokens close the gap further.
- AI agents and delegated clients: an agent acting for a user cannot satisfy a step-up itself. Route the challenge back to the human for approval and treat the resulting token as single-use for that action. See the Cross-Device Flow Security Guide for approval on a second device.
- Machine clients: step-up applies to user authentication. Client credentials tokens have no user event, so sensitive machine operations need other controls such as narrower scopes and approval workflows.
Security considerations from the RFC
- Not an authentication protocol: RFC 9470 section 9 says it must not be used to present OAuth as an authentication protocol. It assumes a separate authentication layer such as OpenID Connect and only carries requirements and results.
- Information leakage in challenges:
acr_valuescan disclose that a resource or a user is high value, which helps targeted phishing. Use generic values and avoid per-user requirements in the header. - Challenge before validation: a resource server may return the challenge before checking the token, but that tells unauthenticated callers what token properties are needed. Validate first unless there is a good reason not to.
- Malicious resource servers: a hostile API could use challenges to trigger user prompts and train users to approve them. Clients should only follow challenges from resource servers they deliberately call, and the authorisation server should show the user which client is asking.
- Prompt quality matters: step-up moves the user to the authorisation server, which is exactly what an attacker's phishing page imitates. Phishing-resistant authenticators bound to the real origin remove that risk.
Decision guidance: step-up or something else
| Approach | Best for | Trade-off |
|---|---|---|
| Strong authentication at every login | Workforce admin portals, small user bases | Simple, but long sessions still go stale; add max_age rules for the riskiest actions |
| RFC 9470 step-up per operation | Consumer and partner APIs with a mix of low and high risk calls | Needs client support for the challenge; best balance of friction and assurance |
| Transaction confirmation with RAR | Payments and approvals where the user must see what they authorise | Heavier integration; binds consent to the transaction details |
| Decoupled approval on another device (CIBA style) | Call centres, agents and devices without a browser | Exposes users to push and approval fatigue; needs number matching or context display |
Smaller organisations can often start with a single high level (phishing-resistant within five minutes) applied to a handful of operations. Larger platforms with many APIs and partners benefit from a central registry of operations and required levels, shared by every resource server and gateway, and from publishing their acr definitions to federation partners.
How to implement
- Classify operations: list sensitive API operations and assign each a required
acrand maximum age. Start with credential changes, payee or recipient changes, exports and admin actions. - Confirm AS support: check
acr_values_supportedin metadata, that the AS putsacrandauth_timein access tokens or introspection, and that it fails rather than downgrades. - Build the policy check: one middleware or gateway policy that reads
acrandauth_time, compares them with the route rule and emits the challenge. - Update clients: handle the 401 challenge, start the authorisation request, keep the original token for normal calls and use the stepped-up token for the sensitive call.
- Run in report-only mode: log would-be challenges for a few weeks to measure how often users would be prompted and fix false positives.
- Enforce per route: turn on enforcement for the highest-risk operations first. Rollback is switching a route back to report-only in the policy, without client changes.
- Tune the experience: measure completion rates, offer passkeys at the step-up prompt and avoid stacking prompts in a single user journey.
Detection and measurement
- Log every challenge with route, required
acrandmax_age, the token'sacrandauth_time, and whether the retry succeeded. - Alert on repeated challenges without successful completion from one session (possible stolen session), on step-ups completed from a new device or location right before a sensitive action, and on any AS token issued below the requested
acr. - Metrics: share of sensitive operations protected by a step-up rule; step-up completion rate; median added time per step-up; share of step-ups completed with phishing-resistant methods; fraud or account takeover losses on protected versus unprotected operations.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | IA-11 Re-authentication | Re-authenticate for defined circumstances such as privileged functions |
| NIST SP 800-53 Rev 5 | IA-2.1, IA-2.2 | Multi-factor authentication for privileged and non-privileged accounts |
| NIST SP 800-53 Rev 5 | AC-12, AU-2 | Session limits and logging of authentication events |
| NIST CSF 2.0 | PR.AA-03, PR.AA-04 | Authentication and protected, verified identity assertions |
| NIST SP 800-63B-4 | AAL2 and AAL3 reauthentication | Ceilings for session and inactivity timeouts |
| MITRE ATT&CK | T1550.001, T1539 | Stolen token and session reuse that step-up constrains |
Common failure patterns
- Checking
acrbut notauth_time: a strong login from yesterday satisfies today's payment. - AS downgrades silently: the AS issues a token at a lower level when the user cannot complete the requested method, and the client loops on challenges.
- Client inspects tokens: the client reads
acrfrom the access token to decide whether to step up, then breaks when the token format changes. - Vendor strings in code: hard-coded
C1or provider-specificacrvalues make migration and federation painful. - Too many prompts: every call demands step-up, users abandon tasks or approve on autopilot, and the control loses value. See the MFA Fatigue and Bypass Guide.
- Step-up as authorisation: a freshly authenticated user is allowed an action their role does not permit.
Practitioner checklist
- List sensitive operations and assign each a required
acrand maximum age. - Publish a small set of namespaced
acrvalues with documented meaning. - Confirm your AS supports
acr_values,max_age,auth_timeand fails on unmet requirements. - Implement the challenge in one policy layer, not per endpoint.
- Validate tokens before issuing challenges.
- Teach clients to handle
insufficient_user_authenticationand retry once. - Run report-only first, then enforce per route with a rollback switch.
- Offer phishing-resistant methods at the step-up prompt.
- Track completion rate and losses on protected operations.
Standards and references
- IETF: RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
- OpenID Foundation: OpenID Connect Core 1.0
- IETF: RFC 9068 JWT Profile for OAuth 2.0 Access Tokens
- IETF: RFC 8176 Authentication Method Reference Values
- NIST: SP 800-63B-4 Authentication and Authenticator Management
- Microsoft Learn: Developer guide to Conditional Access authentication context
Related NHI Mgmt Group resources: OAuth 2.0 and OpenID Connect Guide · OAuth 2.0 Security Best Current Practice (RFC 9700) Guide · Phishing-Resistant MFA Guide · OAuth Scope Design Guide