Join our Newsletter — 33% off our NHI Course
Home› Guides› OAuth Step-Up Authentication Challenge Guide: Implementing RFC 9470…
Guide Identity & Access Management (IAM)

OAuth Step-Up Authentication Challenge Guide: Implementing RFC 9470 for Sensitive API Calls

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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 required acr_values or max_age, and the client sends the user back to the authorisation server with those parameters.
  • Two dimensions, not one: acr describes how the user authenticated and auth_time when; 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 acr as mandatory for access tokens and fail with unmet_authentication_requirements rather 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 acr values 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

  1. The client calls the API with an access token.
  2. The resource server decides the token's authentication event does not meet the requirement for this operation and returns a challenge.
  3. The client redirects the user to the authorisation server with the requested acr_values and/or max_age.
  4. The user authenticates as required and the authorisation server issues a new access token that records the authentication event.
  5. The client retries the call with the new token.
  6. The resource server validates the new acr and auth_time and 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

ItemWhere it appearsMeaning
insufficient_user_authenticationRS challenge, HTTP 401The token's authentication event does not meet the resource's requirement
acr_valuesChallenge and authorisation requestSpace-separated authentication context class references in order of preference; one must be met
max_ageChallenge and authorisation requestMaximum seconds since the last active authentication (user interaction with the AS)
acrJWT access token (RFC 9068), introspection responseThe authentication context class that was satisfied
auth_timeJWT access token, introspection responseTime of the authentication event, in seconds since the Unix epoch
amrID token (OIDC); values registered in RFC 8176Methods used, for example hwk, mfa, otp, pwd
unmet_authentication_requirementsAS error responseThe AS could not satisfy the requested acr
acr_values_supportedAS 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 valueDefinitionRough NIST SP 800-63B equivalentTypical operations
urn:example:acr:basicPassword or single factorAAL1Read profile, browse
urn:example:acr:mfaTwo factors, any typeAAL2Change settings, view statements
urn:example:acr:phrPhishing-resistant: passkey or hardware keyAAL2 or AAL3 depending on authenticatorAdd payee, export data, admin actions
urn:example:acr:phr-hwHardware-bound, non-exportable key with user verificationAAL3Production admin, key release, large payments
  • Freshness by operation: combine acr with max_age. For example, adding a payee might need phr within 300 seconds, while viewing statements needs mfa within 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: acr values are opaque strings. Namespaced URIs avoid collisions when you federate with partners.
  • Do not leak sensitivity: RFC 9470 warns that acr_values can 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

ComponentMust doMust not do
Resource serverValidate the token first; map each sensitive operation to acr and freshness; compare acr and auth_time; return the challenge with 401Treat step-up as permission; challenge before validating the token where that leaks requirements
ClientParse the challenge, start a new authorisation request with the same parameters, retry once with the new token, keep separate tokens per assurance needInspect access token contents (RFC 9470 and RFC 9068 say clients must not); loop on repeated challenges
Authorisation serverTreat requested acr as mandatory for access tokens; include auth_time when max_age is used; advertise acr_values_supportedSilently issue a token at a lower level than requested

Vendor mechanisms compared

  • RFC 9470: standard acr_values and max_age in the Bearer challenge; works with any OpenID Connect provider that honours them.
  • Microsoft Entra ID authentication context: administrators define contexts C1 to C99 and attach Conditional Access policies (for example MFA or a compliant device). The API checks the acrs claim and, if the needed context is missing, returns 401 with error="insufficient_claims", a base64 claims value such as {"access_token":{"acrs":{"essential":true,"value":"C1"}}} and cc_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_values can 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

ApproachBest forTrade-off
Strong authentication at every loginWorkforce admin portals, small user basesSimple, but long sessions still go stale; add max_age rules for the riskiest actions
RFC 9470 step-up per operationConsumer and partner APIs with a mix of low and high risk callsNeeds client support for the challenge; best balance of friction and assurance
Transaction confirmation with RARPayments and approvals where the user must see what they authoriseHeavier integration; binds consent to the transaction details
Decoupled approval on another device (CIBA style)Call centres, agents and devices without a browserExposes 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

  1. Classify operations: list sensitive API operations and assign each a required acr and maximum age. Start with credential changes, payee or recipient changes, exports and admin actions.
  2. Confirm AS support: check acr_values_supported in metadata, that the AS puts acr and auth_time in access tokens or introspection, and that it fails rather than downgrades.
  3. Build the policy check: one middleware or gateway policy that reads acr and auth_time, compares them with the route rule and emits the challenge.
  4. 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.
  5. 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.
  6. 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.
  7. 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 acr and max_age, the token's acr and auth_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

FrameworkReferenceRelevance
NIST SP 800-53 Rev 5IA-11 Re-authenticationRe-authenticate for defined circumstances such as privileged functions
NIST SP 800-53 Rev 5IA-2.1, IA-2.2Multi-factor authentication for privileged and non-privileged accounts
NIST SP 800-53 Rev 5AC-12, AU-2Session limits and logging of authentication events
NIST CSF 2.0PR.AA-03, PR.AA-04Authentication and protected, verified identity assertions
NIST SP 800-63B-4AAL2 and AAL3 reauthenticationCeilings for session and inactivity timeouts
MITRE ATT&CKT1550.001, T1539Stolen token and session reuse that step-up constrains

Common failure patterns

  • Checking acr but not auth_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 acr from the access token to decide whether to step up, then breaks when the token format changes.
  • Vendor strings in code: hard-coded C1 or provider-specific acr values 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 acr and maximum age.
  • Publish a small set of namespaced acr values with documented meaning.
  • Confirm your AS supports acr_values, max_age, auth_time and 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_authentication and 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.