OAuth 2.0 Step Up Authentication Challenge Protocol
Extracted elements (26)
Clients are advised to retain both old (lower-assurance) and new (higher-assurance) tokens rather than replacing the old token, because the new token may be intentionally narrow (e.g., short validity for one-off high-sensitivity calls) and suboptimal for routine operations.
The `acr_values` and `max_age` authorization request parameters are intentionally reused from OpenID Connect (OIDC) rather than defined anew, so any authorization server implementing OpenID Connect can participate in the step-up flow with little or no changes.
The authorization server SHOULD treat the requested `acr` value as a hard requirement (failing with `unmet_authentication_requirements` if unmet) rather than falling back to a weaker ACR, specifically to prevent clients from being stuck in a loop where the AS keeps issuing tokens the RS already rejected.
The specification was motivated by resource servers that require different authentication strengths or recentness based on dynamic, request-time logic opaque to the authorization server (e.g., purchase value thresholds or per-request risk evaluation), which static provisioning-time authorization policies cannot satisfy.
The terms 'authentication level' and 'step up' are explicitly described as metaphors. There is no absolute, interoperable hierarchy of authentication methods; the 'level' concept emerges solely from the resource server's acceptance threshold, not from any standardized ranking.
Because `acr_values` and `max_age` are OPTIONAL parameters already defined in OIDC Section 3.1.2.1, this document introduces no new behavior requirements on authorization servers implementing OpenID Connect; they can participate in the step-up flow without modification.
The `insufficient_user_authentication` error code and the `acr_values`/`max_age` auth-params are defined for the Bearer scheme but are also applicable to other OAuth authentication schemes (such as DPoP per RFC 9449) that use the same error parameter convention.
A client receiving a challenge with the `insufficient_user_authentication` error code SHOULD parse the WWW-Authenticate header for `acr_values` and `max_age` and use them, if present, when constructing a subsequent authorization request.
The `max_age` and `acr_values` auth-params MAY both appear in the same WWW-Authenticate challenge when the resource server needs to express requirements about both authentication recency and authentication level.
The `max_age` auth-param value, whether conveyed as a token or quoted-string per HTTP semantics, MUST represent a non-negative integer.
The resource server MAY return a challenge without verifying that the client presented a valid token; however, doing so leaks the required token properties to an actor who has not proven they can obtain a token for that resource server.
This document MUST NOT be used to position OAuth as an authentication protocol. The specification treats authentication details as handled by a separate layer (e.g., OpenID Connect) and only uses authentication event information as salient context for authorization decisions.
When a request includes the `max_age` parameter, the authorization server MUST include the `auth_time` claim in the issued ID Token (inherited from OIDC Section 3.1.2.1). This ensures the resource server can evaluate authentication recentness.
When processing an authorization request that includes `acr_values`, the authorization server SHOULD consider the requested ACR value as necessary for successfully fulfilling the request; if the requirement cannot be met, the request fails with an `unmet_authentication_requirements` error rather than returning a non-compliant token.
Depending on resource server policy, the `acr_values` in a challenge can reveal context-specific data about the resource or targeted user. Selective high-assurance requirements per user could expose privilege levels to passive observers or active attackers.
Authorization servers advertise support for this specification by including `acr_values_supported` in their OAuth 2.0 Authorization Server Metadata document (RFC 8414), signaling that they will honor `acr_values` and `max_age` in authorization requests.
JWT access tokens use the `auth_time` and `acr` claims (per RFC 9068 Section 2.2.1) to convey the time and context of the user-authentication event. These values are established at authentication time and do not change upon token renewal.
The `acr_values` auth-param for the WWW-Authenticate header conveys a space-separated list of authentication context class reference values in order of preference, indicating which authentication context the resource server requires.
The `insufficient_user_authentication` error code is introduced for the Bearer authentication scheme's error parameter. It signals that the authentication event associated with the presented access token does not meet the resource server's authentication requirements.
The `max_age` auth-param for the WWW-Authenticate header indicates the allowable elapsed time in seconds since the last active authentication event associated with the access token. The value must represent a non-negative integer.
The OAuth 2.0 Token Introspection response is extended with two new top-level members: `acr` (a string identifying the authentication context class reference satisfied) and `auth_time` (a numeric epoch timestamp of when user authentication occurred).
The `insufficient_user_authentication` error value is registered in the OAuth Extensions Error Registry (established by RFC 6749), with usage location 'resource access error response'.
Two new members are registered in the OAuth Token Introspection Response registry (established by RFC 7662): `acr` (Authentication Context Class Reference) and `auth_time` (time when user authentication occurred).
A malicious resource server could abuse the mechanism to trigger unwanted or repeated user interactions at the authorization server. Authorization servers and clients must consider that the step-up trigger can be exploited by an adversary controlling a resource server endpoint.
The `acr_values` parameter in a challenge may unintentionally disclose information about the authenticated user, the resource, or the authorization server. For example, requiring a high assurance ACR only for certain users could identify high-privilege targets for spearphishing. Implementers should carefully consider what to disclose in challenges.
The challenge examination logic (whether a token meets authentication requirements) can be executed before or after conventional token-validation logic. Returning a challenge without token validation leaks required token properties to unauthenticated actors.