OAuth 2.0 Step-up Authentication Challenge Protocol

11 min readNov 18, 2022

(This article is a partial reprint of the article “OAuth 2.0 Step-up Authentication Challenge Protocol” on the Authlete website.)

Overview

OAuth 2.0 Step-up Authentication Challenge Protocol “introduces a mechanism for a resource server to signal to a client that the authentication event associated with the access token of the current request doesn’t meet its authentication requirements and specify how to meet them.” (excerpt from “Abstract”)

As the first step, a client application (a.k.a. relying party) accesses a protected resource endpoint with an access token.

The implementation of the endpoint extracts the access token from the request.

Next, the implementation of the endpoint extracts information about user authentication (which the authorization server performed during the course of issuing the access token) from the access token.

Then, the implementation of the endpoint checks whether the information about user authentication satisfies authentication requirements that the endpoint imposes.

If the requirements are not satisfied, the implementation of the endpoint returns an error response to the client application with information about the authentication requirements.

The diagram below illustrates the flow from making a request with an access token to returning an error response with authentication requirements.

After receiving an error response with authentication requirements, the client application will make an authorization request again. This time, the client application needs to ask the authorization server to issue an access token that satisfies the authentication requirements.

Authentication Requirements

The OAuth 2.0 Step-up Authentication Challenge Protocol specification presumes two types of authentication requirements.

One is authentication context class reference (a.k.a. ACR) of user authentication. The other is maximum authentication age (a.k.a. max age) of user authentication.

Authentication Context Class Reference (ACR)

User authentication is performed somewhere during an authorization flow. OAuth 2.0 and OpenID Connect do not define details about how to authenticate users, but client applications can specify criteria of user authentication by including a list of ACRs in an authorization request.

The authorization server tries to perform user authentication that satisfies at least one of the specified ACRs. However, no error is reported even if the authorization server cannot perform such user authentication unless the acr claim is requested as “essential” (described later).

The acr_values Request Parameter

There are three ways to specify a list of ACRs. The first way is to use the acr_values request parameter. The parameter is defined in Section 3.1.2.1 of OpenID Connect Core 1.0 as follows.

acr_values: OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary Claim by this parameter.

The value of the acr_values request parameter is a space-separated list of ACRs. It appears in an authorization request like the following.

https://as.example.com/authorize?acr_values=acr1+acr2+acr3&...

The claims Request Parameter

The second way to specify a list of ACRs is to use the claims request parameter. The parameter is defined in Section 5.5 of OpenID Connect Core 1.0. The parameter takes a JSON object as a value and the syntax of the JSON is complex.

The following JSON is an example value of the claims request parameter excerpted from OpenID Connect Core 1.0.

{
 "userinfo":
  {
   "given_name": {"essential": true},
   "nickname": null,
   "email": {"essential": true},
   "email_verified": {"essential": true},
   "picture": null,
   "http://example.info/claims/groups": null
  },
 "id_token":
  {
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }
  }
}

This example specifies a list of ACRs that has just one element, urn:mace:incommon:iap:silver. When an authorization request includes this JSON as the value of the claims request parameter, the authorization server tries to perform user authentication that satisfies criteria of urn:mace:incommon:iap:silver.

To make the authorization server return an error when none of the specified ACRs can be satisfied, the client application must request the acr as an essential claim. By adding "essential":true in the JSON object that follows a claim name, the client application can request the claim as essential. In the example below, the auth_time claim and the acr claim are requested as essential.

{
  "id_token":
  {
    "auth_time": {
      "essential": true
    },
    "acr": {
      "values": ["urn:mace:incommon:iap:silver"],
      "essential": true
    }
  }
}

NOTE: The acr_values request parameter cannot request the acr claim as essential.

The default_acr_values Client Metadata

The last way is to use the default_acr_values client metadata. The metadata is defined in Section 2 of OpenID Connect Dynamic Client Registration 1.0 as follows.

default_acr_values: OPTIONAL. Default requested Authentication Context Class Reference values. Array of strings that specifies the default acr values that the OP is being requested to use for processing requests from this Client, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value in the issued ID Token. The acr Claim is requested as a Voluntary Claim by this parameter. The acr_values_supported discovery element contains a list of the supported acr values supported by this server. Values specified in the acr_values request parameter or an individual acr Claim request override these default values.

When an authorization request does not specify a list of ACRs explicitly, the value of the default_acr_values is, if set, used as a list of ACRs.

NOTE: The default_acr_values client metadata cannot request the acr claim as essential.

Unmet Authentication Requirements

If the acr claim is requested as an essential claim, the authorization server returns an error response when none of specified ACRs can be satisfied. If the authorization server supports “OpenID Connect Core Error Code unmet_authentication_requirements”, unmet_authentication_requirements is used as the value of the error response parameter.

The following is the description about the error code in the specification.

unmet_authentication_requirements: The Authorization Server is unable to meet the requirements of the Relying Party for the authentication of the End-User. This error code SHALL be used if the Relying Party wants the OP to conform to a certain Authentication Context Class Reference value using an essential claim acr claim as specified in Section 5.5.1.1. of OpenID Connect Core [OpenID.Core] and the OP is unable to meet this requirement and MAY be used in other cases, if appropriate.

If the authorization server does not support the specification, it is up to the authorization server what error code is used.

Unmet Authentication Requirements for Step-up Authentication

In the context of OpenID Connect Core 1.0, no error is reported even if the authorization server cannot perform such user authentication unless the acr claim is requested as essential.

However, OAuth 2.0 Step-up Authentication Challenge Protocol recommends that an ACR request by the acr_values request parameter (which requests the acr claim as a voluntary claim) be “treated as required” and the authorization server return the unmet_authentication_requirements error in case none of specified ACRs can be satisfied.

The recommendation slightly conflicts with the following paragraph excerpted from OpenID Connect Core 1.0.

Note that even if the Claims are not available because the End-User did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when Claims are not returned, whether they are Essential or Voluntary, unless otherwise specified in the description of the specific claim.

However, in practice, the slight conflict won’t be a big issue.

Actual ACR Values

OpenID Connect Core 1.0 does not define actual ACR values. Therefore, to utilize ACR, it is necessary to define actual ACR values in a deployment-specific way. The following list shows examples of actual ACR values.

urn:openbanking:psd2:ca (UK Open Banking)
urn:openbanking:psd2:sca (UK Open Banking)
urn:cds:au:crd:2 (Australia CDR)
urn:cds:au:cdr:3 (Australia CDR)
urn:brasil:openbanking:loa2 (Open Banking Brasil)
urn:brasil:openbanking:loa3 (Open Banking Brasil)

Authorization servers should advertise information about ACR values they support through their discovery documents. OpenID Connect Discovery 1.0 defines the acr_values_supported server metadata for the purpose as follows.

acr_values_supported: OPTIONAL. JSON array containing a list of the Authentication Context Class References that this OP supports.

Maximum Authentication Age (Max Age)

The previous section states “User authentication is performed somewhere during an authorization flow.” at the beginning. However, in practice, the authorization server may skip the user authentication process if it detects that a user has already been authenticated (= if a user has already logged in). Therefore, the time at which an authorization request was made is not necessarily equal to the time of user authentication that was performed for the authorization request.

The amount of time that has elapsed since the last user authentication is called “authentication age”. A client application may want to ask the authorization server to redo user authentication during an authorization flow in a case where the authentication age exceeds a particular threshold. The threshold is called “maximum authentication age”.

The max_age Request Parameter

Section 3.1.2.1 of OpenID Connect Core 1.0 defines the request parameter max_age as follows in order to enable client applications to specify the maximum authentication age.

max_age: OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. (The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter.) When max_age is used, the ID Token returned MUST include an auth_time Claim Value.

The value of the max_age is an integer that represents the maximum authentication age in seconds. It appears in an authorization request like the following.

https://as.example.com/authorize?max_age=600&...

The default_max_age Client Metadata

If an authorization request does not contain the max_age request parameter but the default_max_age client metadata of the client is set, the value of the metadata is used as the maximum authentication age. The metadata is defined in Section 2 of OpenID Connect Dynamic Client Registration 1.0 as follows.

default_max_age: OPTIONAL. Default Maximum Authentication Age. Specifies that the End-User MUST be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. The max_age request parameter overrides this default value. If omitted, no default Maximum Authentication Age is specified.

The prompt Request Parameter

When a client application wants to ask the authorization server to perform user authentication unconditionally (regardless of whether the maximum authentication age has been reached or not) during an authorization flow, it can use the prompt request parameter with the login value included. Its use will look like the following.

See Section 3.1.2.1 of OpenID Connect Core 1.0 for details about the prompt parameter.

Authentication Requirements Challenge

Protected resource endpoints that utilize the OAuth 2.0 Step-up Authentication Challenge Protocol specification return an error response when the presented access token does not satisfy either or both of the authentication requirements (namely ACR and Max Age).

The diagram below illustrates the flow from returning an error response to making an authorization request asking for an access token that satisfies authentication requirements.

Parameters in the error response are explained in the subsequent sections.

The `insufficient_user_authentication` Error Code

To indicate that the reason of an error response is that authentication requirements are not satisfied, the specification defines an error code insufficient_user_authentication as follows.

insufficient_user_authentication: The authentication event associated with the access token presented with the request doesn’t meet the authentication requirements of the protected resource.

The error code appears in the WWW-Authenticate HTTP header of an error response as shown below.

WWW-Authenticate: Bearer error="insufficient_user_authentication",...

The `acr_values` Parameter

To list ACRs one of which an access token must satisfy, the specification defines a parameter acr_values as follows.

acr_values: A space-separated string listing the authentication context class reference values, in order of preference, one of which the protected resource requires for the authentication event associated with the access token.

The parameter is used in conjunction with the error code insufficient_user_authentication like below (excerpt from the specification):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="A different authentication level is required",
  acr_values="myACR"

If a client application receives the error response above, the client application needs to make an authorization request that requests the acr claim as an essential with myACR included in values like below. Line-breaks in the example below are for display purposes only. An actual request does not contain line-breaks.

https://as.example.com/authorize?claims={
    "id_token": {
        "acr": {
            "essential": true,
            "values": [ "myACR" ]
        }
    }
}&...

NOTE: If the authorization server treats the acr_values request parameter in the way recommended by the OAuth 2.0 Step-up Authentication Challenge Protocol specification, acr_values=myACR would be enough.

The `max_age` Parameter

To indicate the maximum authentication age which an access token must satisfy, the specification defines a parameter max_age as follows.

max_age: Indicates the allowable elapsed time in seconds since the last active authentication event associated with the access token.

The parameter is used in conjunction with the error code insufficient_user_authentication like below (excerpt from the specification):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="More recent authentication is required",
  max_age="5"

If a client application receives the error response above, the client application needs to make an authorization request with the prompt request parameter with login included.

Authentication Information Bound To Access Token

To enable protected resource endpoints to check whether a presented access token satisfies authentication requirements or not, the access token must hold information about the user authentication that was performed during the course of issuing the access token.

The OAuth 2.0 Step-up Authentication Challenge Protocol specification defines the following two attributes of access token that may appear in the payload part of JWT access tokens and the message body of token introspection responses (cf. RFC 7662).

acr: Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the user authentication performed satisfied.
auth_time: Time when the user authentication occurred. A JSON numeric value representing the number of seconds from 1970–01–01T00:00:00Z UTC until the time of date/time of the authentication event.

The JSON below is an example excerpted from the specification that shows how the acr and auth_time attributes appear in the payload part of JWT access tokens.

{
    "active": true,
    "client_id": "s6BhdRkqt3",
    "scope": "purchase",
    "sub": "someone@example.net",
    "aud": "https://rs.example.com",
    "iss": "https://as.example.net",
    "exp": 1639528912,
    "iat": 1618354090,
    "auth_time": 1646340198,
    "acr": "myACR"
}

Authlete’s Implementation

Authlete supports the OAuth 2.0 Step-up Authentication Challenge Protocol specification since version 2.3.

See “Authlete’s Implementation” on the Authlete website for further details.

Finally

As of this writing (in November 2022), Authlete 2.3 is under development and its stable version has not been publicly released yet. If you are interested in early access to the latest Authlete version, please contact us.