<?xml version='1.0' encoding='utf-8'?> version="1.0" encoding="UTF-8"?>

<!DOCTYPE rfc [
  <!ENTITY nbsp    "&#160;">
  <!ENTITY zwsp   "&#8203;">
  <!ENTITY nbhy   "&#8209;">
  <!ENTITY wj     "&#8288;">
]>
<!-- name="GENERATOR" content="github.com/mmarkdown/mmark Mmark Markdown Processor - mmark.miek.nl" -->

<rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" ipr="trust200902" docName="draft-ietf-oauth-step-up-authn-challenge-17" number="9470" submissionType="IETF" category="std" consensus="true" tocInclude="true" symRefs="true" updates="" obsoletes="" xml:lang="en" consensus="true"> sortRefs="true">

<front>
  <title abbrev="OAuth Authn Auth Challenge">OAuth 2.0 Step-up Step Up Authentication Challenge Protocol</title><seriesInfo value="draft-ietf-oauth-step-up-authn-challenge-17" stream="IETF" status="standard" name="Internet-Draft"/> Protocol</title>
  <seriesInfo name="RFC" value="9470"/>
  <author initials="V." surname="Bertocci" fullname="Vittorio Bertocci"><organization>Auth0/Okta</organization><address><postal><street/>
</postal><email>vittorio@auth0.com</email> Bertocci">
    <organization>Auth0/Okta</organization><address>
    <email>vittorio@auth0.com</email>
  </address></author>

  <author initials="B." surname="Campbell" fullname="Brian Campbell"><organization>Ping Identity</organization><address><postal><street/>
</postal><email>bcampbell@pingidentity.com</email> Campbell">
    <organization>Ping Identity</organization><address>
    <email>bcampbell@pingidentity.com</email>
  </address></author>
<date/>
<area>Security</area>
<workgroup>Web Authorization Protocol</workgroup>
  <date year="2023" month="August"/>

  <area>sec</area>
  <workgroup>oauth</workgroup>

  <keyword>security</keyword>
  <keyword>oauth2</keyword>
  <keyword>openid connect</keyword>
  <keyword>oauth</keyword>
<keyword>step-up</keyword>
  <keyword>step up</keyword>

<abstract>
<t>It is not uncommon for resource servers to require different authentication strengths or recentness according to the characteristics of a request. This document introduces a mechanism for a that resource server servers can use to signal to a client that the authentication event associated with the access token of the current request does not meet its authentication requirements and specify and, further, how to meet them.
This document also codifies a mechanism for a client to request that an authorization server achieve a specific authentication strength or recentness when processing an authorization request.</t>
</abstract>

<note title="Discussion Venues" removeInRFC="true">
<t>Discussion of this document takes place on the
    Web Authorization Protocol Working Group mailing list (oauth@ietf.org),
    which is archived at <eref target="https://mailarchive.ietf.org/arch/browse/oauth/"/>.</t>
<t>Source for this draft can be found at
    <eref target="https://github.com/oauth-wg/oauth-step-up-authn-challenge"/>.</t>
</note>
</front>

<middle>

<section anchor="Introduction"><name>Introduction</name>
<t>In simple API authorization scenarios, an authorization server will determine what authentication technique to use to handle a given request on the basis of aspects such as the scopes requested, the resource, the identity of the client client, and other characteristics known at provisioning time.
Although the that approach is viable in many situations, it falls short in several important circumstances. Consider, for instance, an eCommerce API requiring different authentication strengths depending on whether the item being purchased exceeds a certain threshold, dynamically estimated by the API itself using a logic that is opaque to the authorization server.
An API might also determine that  a more recent user authentication is required based on its own risk evaluation of the API request.</t>
<t>This document extends the collection of error codes collection defined by <xref target="RFC6750"/> with a new value, <tt>insufficient_user_authentication</tt>, which can be used by resource servers to signal to the client that the authentication event associated with the access token presented with the request does not meet the authentication requirements of the resource server.
This document also introduces <tt>acr_values</tt> and <tt>max_age</tt> parameters for the <tt>Bearer</tt> authentication scheme challenge defined by <xref target="RFC6750"/>, which the target="RFC6750"/>.  The resource server can use these parameters to explicitly communicate to the client the required authentication strength or recentness.</t>
<t>The client can use that information to reach back to the authorization server with an authorization request specifying that specifies the authentication requirements indicated by the protected resource, resource.   This is accomplished by including the <tt>acr_values</tt> or <tt>max_age</tt> authorization request parameters as defined in <xref target="OIDC"/>.</t>
<t>Those extensions will make it possible to implement interoperable step up authentication with minimal work from resource servers, clients clients, and authorization servers.</t>

<section anchor="conventions-and-terminology"><name>Conventions and Terminology</name>
<t>The
        <t>
    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
    "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
    NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
    "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
    "<bcp14>MAY</bcp14>", and "OPTIONAL" "<bcp14>OPTIONAL</bcp14>" in this document are
    to be interpreted as described in BCP 14 BCP&nbsp;14 <xref target="RFC2119"/>
    <xref target="RFC8174"/> when, and only when, they appear in all capitals,
    as shown here.</t> here.
        </t>
<t>This specification uses the terms "access token", "authorization server", "authorization endpoint", "authorization request", "client", "protected resource", and "resource server" defined by The OAuth 2.0 Authorization Framework "<xref target="RFC6749" format="title"/>" <xref target="RFC6749"/>.</t>
</section>
</section>

<section anchor="protocol-overview"><name>Protocol Overview</name>
<t>The following is an end-to-end sequence of a typical step-up step up authentication scenario implemented according to this specification.
The scenario assumes that, before the sequence described below takes place, the client already obtained an access token for the protected resource.</t>

<figure anchor="abstract-flow"><name>Abstract protocol flow Protocol Flow </name>
<artwork>+----------+
<artwork name="" type="" align="left" alt=""><![CDATA[
+----------+                                          +--------------+
|          |                                          |              |
|          |-----------(1) request ------------------&gt;| ------------------>|              |
|          |                                          |              |
|          |&lt;---------(2)          |<---------(2) challenge ------------------|   Resource   |
|          |                                          |    Server    |
|  Client  |                                          |              |
|          |-----------(5) request ------------------&gt;| ------------------>|              |
|          |                                          |              |
|          |&lt;-----(6)          |<-----(6) protected resource -------------|              |
|          |                                          +--------------+
|          |
|          |
|          |  +-------+                              +---------------+
|          |-&gt;|          |->|       |                              |               |
|          |  |       |--(3) authorization request--&gt;| request-->|               |
|          |  | User  |                              |               |
|          |  | Agent |&lt;-----------[...]------------&gt;| |<-----------[...]------------>| Authorization |
|          |  |       |                              |     Server    |
|          |&lt;-|          |<-|       |                              |               |
|          |  +-------+                              |               |
|          |                                         |               |
|          |&lt;--------          |<-------- (4) access token --------------|               |
|          |                                         |               |
+----------+                                         +---------------+
</artwork>
]]></artwork>
</figure>

<ol>

<ol spacing="normal">
<li>The client requests a protected resource, presenting an access token.</li>
<li>The resource server determines that the circumstances in which the presented access token was obtained offer insufficient authentication strength and/or recentness, hence recentness; hence, it denies the request and returns a challenge describing (using a combination of <tt>acr_values</tt> and <tt>max_age</tt>) what authentication requirements must be met for the resource server to authorize a request.</li>
<li>The client directs the user agent to the authorization server with an authorization request that includes the <tt>acr_values</tt> and/or <tt>max_age</tt> indicated by the resource server in the previous step.</li>
<li>After whatever
<li>Whatever sequence required by the grant of choice plays out, which out; this will include the necessary steps to authenticate the user in accordance with the <tt>acr_values</tt> and/or <tt>max_age</tt> values of the authorization request, request.  Then, the authorization server returns a new access token to the client. The new access token contains or references information about the authentication event.</li>
<li>The client repeats the request from step 1, presenting the newly obtained access token.</li>
<li>The resource server finds that the user authentication performed during the acquisition of the new access token complies with its requirements, requirements and returns the representation of the requested protected resource.</li>
</ol>
<t>The validation operations mentioned in step steps 2 and 6 imply that the resource server has a way of evaluating the authentication that occurred during the process by which the access token was obtained. In the context of this document, the assessment by the resource server of the specific authentication method used to obtain a token for the requested resource is called an "authentication level." level". This document will describe how the resource server can perform this assessment of an "authentication level" authentication level when the access token is a JWT Access token JSON Web Token (JWT) <xref target="RFC9068"/> or is validated via introspection <xref target="RFC7662"/>. Other methods of determining the authentication level by which the access token was obtained are possible, per agreement by the authorization server and the protected resource, but they are beyond the scope of this specification. Given an authentication level of a token, the resource server determines whether it meets the security criteria for the requested resource.</t>
<t>"Authentication
<t>The terms "authentication level" and "step-up" "step up" are metaphors in this specification. These metaphors do not suggest that there is an absolute hierarchy of authentication methods expressed in interoperable fashion. The notion of a level emerges from the fact that the resource server may only want to accept certain authentication methods. When presented with a token derived from a particular authentication method (i.e., a given authentication level) that it does not want to accept (i.e., below the threshold or level it will accept), the resource server seeks to "step-up" step up (i.e., renegotiate) from the current authentication level to one that it may accept. The "step-up" "step up" metaphor is intended to convey a shift from the original authentication level to one that is acceptable to the resource server.</t>
<t>Although the case in which the new access token supersedes old tokens by
virtue of a higher authentication level is common, in line with the intuition connotation
of the term "step-up authentication" suggests, "step up authentication", it is important to keep in mind
that this might not necessarily hold true in the general case.  For example: example, for a particular request, a
resource server might require for a particular request a higher authentication
level and a shorter validity, resulting in a token suitable for one-off calls
but leading to frequent prompts, hence prompts: hence, offering a suboptimal user experience, experience if the token is reused
for routine operations. In those scenarios, such a scenario, the client would be better served
by keeping both the old tokens, which are associated with a lower authentication level,
and the new one - one: selecting the appropriate token for each API call. This is
not a new requirement for clients, as incremental consent and least privilege least-privilege
principles will require similar heuristics for managing access tokens
associated to with different scopes and permission levels. This document does not
recommend any specific token caching strategy, as token-caching strategy: that choice will be dependent on
the characteristics of every particular scenario and remains
application-dependent as in the core OAuth cases.  Also recall that OAuth 2.0
<xref target="RFC6749"/> assumes access tokens are treated as opaque by
clients. The token format might be unreadable to the client or might change at
any time to become unreadable. So, during the course of any token caching token-caching
strategy, a client must not attempt to inspect the content of the access token
to determine the associated authentication information or other details (see Section 6 of
<xref target="RFC9068"/> target="RFC9068" sectionFormat="of" section="6"/> for a more detailed
discussion).</t>
</section>

<section anchor="Challenge"><name>Authentication Requirements Challenge</name>

<t>This specification introduces a new error code value for the <tt>error</tt> parameter of the challenge of the <tt>Bearer</tt> authentication scheme from scheme's <tt>error</tt> parameter (from <xref target="RFC6750"/> target="RFC6750"/>) and other OAuth authentication schemes, such as those seen in <xref target="I-D.ietf-oauth-dpop"/>, target="RFC9449"/>, which use the same <tt>error</tt> parameter:</t>

<dl>
<dt><tt>insufficient_user_authentication</tt></dt>

<dl spacing="normal">
<dt><tt>insufficient_user_authentication</tt>:</dt>
<dd>The authentication event associated with the access token presented with the request does not meet the authentication requirements of the protected resource.</dd>
</dl>

<t>Note: the logic through which the resource server determines that the current request does not meet the authentication requirements of the protected resource, and associated functionality (such as expressing, deploying and publishing such requirements) requirements), is out of scope for this document.</t>
<t>Furthermore, this specification defines the following <tt>WWW-Authenticate</tt> auth-param values for those OAuth authentication schemes to convey the authentication requirements back to the client.</t>

<dl>
<dt><tt>acr_values</tt></dt>

<dl spacing="normal">
  <dt><tt>acr_values</tt>:</dt>

<dd>A space-separated string listing the authentication context class reference values, values in order of preference, one of which the preference. The protected resource requires one of these values for the authentication event associated with the access token. The authentication context, as As defined in section Section 1.2 of <xref target="OIDC"/> target="OIDC"/>, the authentication context conveys information about how authentication takes place (e.g., what authentication method(s) or assurance level to meet).</dd>
<dt><tt>max_age</tt></dt>
<dd>Indicates
<dt><tt>max_age</tt>:</dt>
<dd>This value indicates the allowable elapsed time in seconds since the last active authentication event associated with the access token. An active authentication event entails a user interacting with the authorization server in response to an authentication prompt. Note that that, while the auth-param value can be conveyed as a token or quoted-string (see section 11.2 of <xref target="RFC9110"/>), target="RFC9110" sectionFormat="of" section="11.2"/>), it has to represent a non-negative integer.</dd>
</dl>
<t><xref target="acr-challenge"/> below is an example of a <tt>Bearer</tt> authentication scheme challenge with the <tt>WWW-Authenticate</tt> header using using:</t>
<ul><li>
  the <tt>insufficient_user_authentication</tt> error code value to inform the client that the access token presented is not sufficient to gain access to the protected resource, and the and</li>
  <li>the <tt>acr_values</tt> parameter to let the client know that the expected authentication level corresponds to the authentication context class reference identified by <tt>myACR</tt>.</t> <tt>myACR</tt>.</li></ul>
<t>Note that while this specification only defines usage of the above auth-params with the <tt>insufficient_user_authentication</tt> error code, it does not preclude future specifications or profiles from defining their usage with other error codes.</t>

<figure anchor="acr-challenge"><name>Authentication anchor="acr-challenge">
<name>Authentication Requirements Challenge indicating Indicating <tt>acr_values</tt> </name>
<artwork>HTTP/1.1
<sourcecode type="http-message"><![CDATA[HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="A different authentication level is required",
  acr_values="myACR"
</artwork>
]]></sourcecode>
</figure>

<t>The following example in <xref target="age-challenge"/> shows a challenge informing the client that the last active authentication event associated with the presented access token is too old and a more recent authentication is needed.</t>

<figure anchor="age-challenge"><name>Authentication anchor="age-challenge">
<name>Authentication Requirements Challenge indicating Indicating <tt>max_age</tt> </name>
<artwork>HTTP/1.1
<sourcecode type="http-message"><![CDATA[HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="More recent authentication is required",
  max_age="5"
</artwork>
]]></sourcecode>
</figure>

<t>The auth-params <tt>max_age</tt> and <tt>acr_values</tt> MAY <bcp14>MAY</bcp14> both occur in the same challenge if the resource server needs to express requirements both about both recency and authentication levels. level.
If the resource server determines that the request is also lacking the scopes required by the requested resource, it MAY <bcp14>MAY</bcp14> include the <tt>scope</tt> attribute with the scope value necessary to access the protected resource, as described in section 3.1 of <xref target="RFC6750"/>.</t> target="RFC6750" sectionFormat="of" section="3.1"/>.</t>
</section>

<section anchor="authorization-request"><name>Authorization Request</name>
<t>A client receiving a challenge from the resource server carrying the <tt>insufficient_user_authentication</tt> error code <tt>insufficient_user_authentication</tt> SHOULD <bcp14>SHOULD</bcp14> parse the <tt>WWW-Authenticate</tt> header for  <tt>acr_values</tt> and <tt>max_age</tt> and use them, if present, in constructing an authorization request, which request. This request is then conveyed to the authorization server's authorization endpoint via the user agent in order to obtain a new access token complying with the corresponding requirements.
Both
The <tt>acr_values</tt> and <tt>max_age</tt> authorization request parameters are OPTIONAL both <bcp14>OPTIONAL</bcp14> parameters defined in Section 3.1.2.1. of <xref target="OIDC"/>. This document does not introduce any changes in the authorization server behavior defined in <xref target="OIDC"/> for processing those parameters, hence parameters; hence, any authorization server implementing OpenID Connect will be able to participate in the flow described here with little or no changes. See <xref target="AuthzResp"/> for more details.</t>
<t>The example authorization request URI below, which might be used after receiving the challenge in <xref target="acr-challenge"/>, indicates to the authorization server that the client would like the authentication to occur according to the authentication context class reference identified by <tt>myACR</tt>.</t>
<figure><name>Authorization Request indicating Indicating <tt>acr_values</tt>
</name>
<artwork>https://as.example.net/authorize?client_id=s6BhdRkqt3
&amp;response_type=code&amp;scope=purchase&amp;acr_values=myACR
</artwork>
<artwork><![CDATA[https://as.example.net/authorize?client_id=s6BhdRkqt3
&response_type=code&scope=purchase&acr_values=myACR
]]></artwork>
</figure>
<t>After the challenge in <xref target="age-challenge"/>, a client might direct the user agent to the following example authorization request URI where the <tt>max_age</tt> parameter indicates to the authorization server that the user authentication user-authentication event needs to have occurred no more than five seconds prior.</t>
<figure><name>Authorization Request indicating Indicating <tt>max_age</tt>
</name>
<artwork>https://as.example.net/authorize?client_id=s6BhdRkqt3
&amp;response_type=code&amp;scope=purchase&amp;max_age=5
</artwork>
<artwork><![CDATA[https://as.example.net/authorize?client_id=s6BhdRkqt3
&response_type=code&scope=purchase&max_age=5
]]></artwork>
</figure>
</section>

<section anchor="AuthzResp"><name>Authorization Response</name>

<t>Section 5.5.1.1 of <xref target="OIDC"/>  establishes that an authorization server receiving a request containing the <tt>acr_values</tt> parameter MAY <bcp14>MAY</bcp14> attempt to authenticate the user in a manner that satisfies the requested Authentication Context Class Reference, authentication context class reference and include the corresponding value in the <tt>acr</tt> claim in the resulting ID Token. The same section also establishes that that, in case the desired authentication level cannot be met, the authorization server SHOULD <bcp14>SHOULD</bcp14> include in the <tt>acr</tt> claim a value reflecting the authentication level of the current session (if any). any) in the <tt>acr</tt> claim. Furthermore, Section 3.1.2.1 <xref target="OIDC"/> states that if a request includes the <tt>max_age</tt> parameter, the authorization server MUST <bcp14>MUST</bcp14> include the <tt>auth_time</tt> claim in the issued ID Token.
An authorization server complying with this specification will react to the presence of the <tt>acr_values</tt> and <tt>max_age</tt> parameters by including <tt>acr</tt> and <tt>auth_time</tt> in the access token (see <xref target="authn-info-in-at"/> for details).
Although <xref target="OIDC"/> leaves the authorization server free to decide how to handle the inclusion of <tt>acr</tt> in the ID Token when requested via <tt>acr_values</tt>, when it comes to access tokens in this specification, the authorization server SHOULD <bcp14>SHOULD</bcp14> consider the requested acr value as necessary for successfully fulfilling the request.  That is, the requested <tt>acr</tt> value is included in the access token if the authentication operation successfully met its requirements, or that requirements; otherwise,
the authorization request fails in all other cases, returning and returns an <tt>unmet_authentication_requirements</tt> error as defined in <xref target="OIDCUAR"/>. The recommended behavior will help prevent clients getting stuck in a loop where the authorization server keeps returning tokens that the resource server already identified as not meeting its requirements hence known to be rejected as well.</t> requirements.</t>
</section>

<section anchor="authn-info-in-at"><name>Authentication Information Conveyed via Access Token</name>
<t>To evaluate whether an access token meets the protected resource's requirements, the resource server needs a way of accessing information about the authentication event by which that access token was obtained. This specification provides guidance on how to convey that information in conjunction with two common access token validation methods: the access-token-validation methods:</t>
<ul>
  <li>the one described in <xref target="RFC9068"/>, where the access token is encoded in JWT format and verified via a set of validation rules, and and</li>
  <li> the one described in <xref target="RFC7662"/>, where the token is validated and decoded by sending it to an introspection endpoint.
Authorization endpoint.</li></ul>
<t>Authorization servers and resource servers MAY <bcp14>MAY</bcp14> elect to use other encoding and validation methods, however methods; however, those are out of scope for this document.</t>

<section anchor="jwt-access-tokens"><name>JWT Access Tokens</name>

<t>When access tokens are represented as JSON Web Tokens (JWT) (JWTs) <xref target="RFC7519"/>, the <tt>auth_time</tt> and <tt>acr</tt> claims (per Section 2.2.1 of <xref target="RFC9068"/>) target="RFC9068" sectionFormat="of" section="2.2.1"/>) are used to convey the time and context of the user authentication user-authentication event that the authentication server performed during the course of obtaining the access token. It is useful to bear in mind that the values of those two parameters are established at user authentication user-authentication time and will not change in the event of access token renewals. See the aforementioned Section 2.2.1 of <xref target="RFC9068"/> target="RFC9068" sectionFormat="of" section="2.2.1"/> for details. The following is a conceptual example showing the decoded content of such a JWT access token.</t>

<figure>
<artwork>Header:
  <name>Decoded JWT Access Token</name>
<sourcecode type="json"><![CDATA[Header:

{"typ":"at+JWT","alg":"ES256","kid":"LTacESbw"}

Claims:

{
 "iss": "https://as.example.net",
 "sub": "someone@example.net",
 "aud": "https://rs.example.com",
 "exp": 1646343000,
 "iat": 1646340200,
 "jti" : "e1j3V_bKic8-LAEB_lccD0G",
 "client_id": "s6BhdRkqt3",
 "scope": "purchase",
 "auth_time": 1646340198,
 "acr": "myACR"
}
</artwork>
]]></sourcecode>
</figure>
</section>

<section anchor="introspect"><name>OAuth 2.0 Token Introspection</name>
<t>OAuth 2.0 Token Introspection
<t>"<xref target="RFC7662" format="title"/>" <xref target="RFC7662"/> defines a method for a protected resource to query an authorization server about the active state of an access token as well as to determine metainformation about the token.
The following two top-level introspection response members are defined to convey information about the user authentication user-authentication event that the authentication server performed during the course of obtaining the access token.</t>

<dl>
<dt><tt>acr</tt></dt>
<dd>Authentication Context Class Reference. String

<dl spacing="normal">
<dt><tt>acr</tt>:</dt>
<dd>String specifying an Authentication Context Class Reference authentication context class reference value that identifies the Authentication Context Class authentication context class that was satisfied by the user authentication performed satisfied.</dd>
<dt><tt>auth_time</tt></dt> user-authentication event performed.</dd>
<dt><tt>auth_time</tt>:</dt>
<dd>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.</dd>
</dl>
<t>The following example shows an introspection response with information about the user authentication user-authentication event by which the access token was obtained.</t>

<figure>
<artwork>HTTP/1.1
  <name>Introspection Response</name>
<sourcecode type="http-message"><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json

{
  "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"
}
</artwork>
]]></sourcecode>
</figure>

</section>
</section>

<section anchor="ASMetadata"><name>Authorization Server Metadata</name>
<t>Authorization Servers servers can advertise their support of this specification by including in their metadata document (as document, as defined in <xref target="RFC8414"/>) target="RFC8414"/>, the value <tt>acr_values_supported</tt> <tt>acr_values_supported</tt>, as defined in section Section 3 of <xref target="OIDCDISC"/>. The presence of <tt>acr_values_supported</tt> in the authorization server metadata document signals that the authorization server will understand and honor the <tt>acr_values</tt> and <tt>max_age</tt> parameters in incoming authorization requests.</t>
</section>

<section anchor="Deployment"><name>Deployment Considerations</name>

<t>This specification facilitates the communication of requirements from a resource server to a client, which which, in turn turn, can enable a smooth step-up step up authentication experience. However, it is important to realize that the user experience achievable in every specific deployment is a function of the policies each resource server and authorization server pairs establish. pair establishes. Imposing constraints on those policies is out of scope for this specification, hence specification; hence, it is perfectly possible for resource servers and authorization servers to impose requirements that are impossible for users to comply with, with or leading that lead to an undesirable user experience user-experience outcome.
The authentication prompts presented by the authorization server as a result of the method of propagating authentication requirements described here might require the user to perform some specific actions such as using multiple devices, having access to devices complying with specific security requirements, and so on. Those extra requirements, concerning that are more about concerned with how to comply with a particular requirement rather than indicating the identifier of the requirement itself, are out of scope for this specification.</t>
</section>

<section anchor="Security"><name>Security Considerations</name>
<t>This specification adds to previously defined OAuth mechanisms.  Their respective Security Considerations apply - OAuth security considerations apply:</t>

<ul>
  <li>OAuth 2.0 <xref target="RFC6749"/>, JWT target="RFC6749"/>,</li>
  <li>JWT access tokens <xref target="RFC9068"/>, Bearer WWW-Authentication target="RFC9068"/>,</li>
  <li>Bearer <tt>WWW-Authenticate</tt> <xref target="RFC6750"/>, token target="RFC6750"/>,</li>
  <li>token introspection <xref target="RFC7662"/>, and authorization and</li>
  <li>authorization server metadata <xref target="RFC8414"/>.</t> target="RFC8414"/>.</li></ul>
<t>This document MUST NOT <bcp14>MUST NOT</bcp14> be used to position OAuth as an authentication protocol. For the purposes of this specification, the way in which a user authenticated with the authorization server to obtain an access token is salient information, as a resource server might decide whether to grant access on the basis of how that authentication operation was performed. Nonetheless, this specification does not attempt to define the mechanics by which authentication takes place, relying on a separate authentication layer to take care of the details. In line with other specifications of the OAuth family, this document assumes the existence of a session without going into the details of how it is established or maintained, what protocols are used to implement that layer (e.g., OpenID Connect), and so forth.
Depending on the policies adopted by the resource server, the <tt>acr_values</tt> parameter introduced in <xref target="Challenge"/> might unintentionally disclose information about the authenticated user, the resource itself, the authorization server, and any other context-specific data that an attacker might use to gain knowledge about their target.
For example, a resource server requesting an acr value corresponding to a high level of assurance for some users but not others might identify possible high privilege high-privilege users to target with spearhead phishing attacks.
Implementers should use care in determining what to disclose in the challenge and in what circumstances.
The logic examining the incoming access token to determine whether or not a challenge should be returned can execute be executed either before or after the conventional token validation token-validation logic, be it based on JWT token validation, introspection, or any other method. The resource server MAY <bcp14>MAY</bcp14> return a challenge without verifying the client presented a valid token. However, this approach will leak the required properties of an authorization token to an actor who has not proven they can obtain a token for this resource server.</t>
<t>As this specification provides a mechanism for the resource server to trigger user interaction, it's important for the authorization server and clients to consider that a malicious resource server might abuse of that feature.</t>
</section>

<section anchor="IANA"><name>IANA Considerations</name>

<section anchor="oauth-extensions-error-registration"><name>OAuth Extensions Error Registration</name>
<t>This specification requests registration of registers the following error value in the "OAuth Extensions Error" registry Error Registry" <xref target="IANA.OAuth.Params"/> established by <xref target="RFC6749"/>.</t>

<ul>
<li>Name: <tt>insufficient_user_authentication</tt></li>
<li>Usage Location: resource

<dl spacing="compact" newline="false">
<dt>Name:</dt>
<dd><tt>insufficient_user_authentication</tt></dd>
<dt>Usage Location:</dt>
<dd>resource access error response</li>
<li>Protocol Extension: OAuth response</dd>
<dt>Protocol Extension:</dt>
<dd>OAuth 2.0 Step-up Step Up Authentication Challenge Protocol</li>
<li>Change controller: IETF</li>
<li>Specification document(s): <xref Protocol</dd>
<dt>Change controller:</dt>
<dd>IETF</dd>
<dt>Specification document(s):</dt>
<dd><xref target="Challenge"/> of [[ this specification ]]</li>
</ul> RFC 9470</dd>
</dl>
</section>

<section anchor="oauth-token-introspection-response-registration"><name>OAuth Token Introspection Response Registration</name>
<t>This specification requests registration of registers the following values in the "OAuth Token Introspection Response" registry <xref target="IANA.OAuth.Params"/> established by <xref target="RFC7662"/>.</t>
<t>Authentication Context Class Reference:</t>

<ul>
<li>Name: <tt>acr</tt></li>
<li>Description: Authentication

<dl spacing="compact" newline="false">
<dt>Name:</dt>
<dd><tt>acr</tt></dd>
<dt>Description:</dt>
<dd>Authentication Context Class Reference</li>
<li>Change Controller: IETF</li>
<li>Specification Document(s): <xref Reference</dd>
<dt>Change Controller:</dt>
<dd>IETF</dd>
<dt>Specification Document(s):</dt>
<dd><xref target="introspect"/> of [[ this specification ]]</li>
</ul> RFC 9470</dd>
</dl>
<t>Authentication Time:</t>

<ul>
<li>Name: <tt>auth_time</tt></li>
<li>Description: Time

<dl spacing="compact" newline="false">
<dt>Name:</dt>
<dd><tt>auth_time</tt></dd>
<dt>Description:</dt>
<dd>Time when the user authentication occurred</li>
<li>Change Controller: IETF</li>
<li>Specification Document(s): <xref occurred</dd>
<dt>Change Controller:</dt>
<dd>IETF</dd>
<dt>Specification Document(s):</dt>
<dd><xref target="introspect"/> of [[ this specification ]]</li>
</ul> RFC 9470</dd>
</dl>
</section>
</section>

</middle>

<back>

<back><references>
  <name>References</name>
<references><name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6750.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
</references>
<references><name>Informative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.ietf-oauth-dpop.xml"/>

<!-- [I-D.ietf-oauth-dpop] in AUTH48 state as of 08/15/23; RFC 9449 -->

<!--[rfced] Please note that we have updated the reference to
     draft-ietf-oauth-dpop-16 to instead point to its RFC-to-be number
     (as that document entered AUTH48 prior to this one).  Note that
     if this document completes AUTH48 prior to
     draft-ietf-oauth-dpop-16, we can:

    1) revert the reference to point to the I-D, or
    2) hold publication until RFC 9449 completes AUTH48.

Please let us know your preference.

[rfced] Authors prefer to wait for 9449.
-->

<reference anchor="RFC9449" target="https://www.rfc-editor.org/info/rfc9449">
<front>
<title>OAuth 2.0 Demonstrating Proof of Possession at the Application Layer (DPoP)</title>
<author initials='D' surname='Fett' fullname='Daniel Fett'>
<organization />
</author>
<author initials='B' surname='Campbell' fullname='Brian Campbell'>
<organization />
</author>
<author initials='J' surname='Bradley' fullname='John Bradley'>
<organization />
</author>
<author initials='T' surname='Lodderstedt' fullname='Torsten Lodderstedt'>
<organization />
</author>
<author initials='M' surname='Jones' fullname='Michael Jones'>
<organization />
</author>
<author initials='D' surname='Waite' fullname='David Waite'>
<organization />
</author>
<date year='2023' month='August'/>
</front>
<seriesInfo name="RFC" value="9449"/>
<seriesInfo name="DOI" value="10.17487/RFC9449"/>
</reference>

<reference anchor="IANA.OAuth.Params" target="https://www.iana.org/assignments/oauth-parameters">
  <front>
    <title>OAuth Parameters</title>
    <author>
      <organization>IANA</organization>
    </author>
    <date/>
  </front>
</reference>

<reference anchor="OIDC" target="https://openid.net/specs/openid-connect-core-1_0.html">
  <front>
    <title>OpenID Connect Core 1.0 incorporating errata set 1</title>
    <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
      <organization>NRI</organization>
    </author>
    <author fullname="John Bradley" initials="J." surname="Bradley">
      <organization>Ping Identity</organization>
    </author>
    <author fullname="Mike Jones" initials="M." surname="Jones">
      <organization>Microsoft</organization>
    </author>
    <author fullname="Breno de Medeiros" initials="B." surname="de Medeiros">
      <organization>Google</organization>
    </author>
    <author fullname="Chuck Mortimore" initials="C." surname="Mortimore">
      <organization>Salesforce</organization>
    </author>
    <date year="2014" month="Nov" day="8"/>
  </front>
</reference>

<reference anchor="OIDCDISC" target="https://openid.net/specs/openid-connect-discovery-1_0.html">
  <front>
    <title>OpenID Connect Core Discovery 1.0 incorporating errata set 1</title>
    <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
      <organization>NRI</organization>
    </author>
    <author fullname="John Bradley" initials="J." surname="Bradley">
      <organization>Ping Identity</organization>
    </author>
    <author fullname="Mike Jones" initials="M." surname="Jones">
      <organization>Microsoft</organization>
    </author>
    <author fullname="Edmund Jay" initials="E." surname="Jay">
      <organization>Illumila</organization>
    </author>
    <date year="2014" month="Nov" day="8"/>
  </front>
</reference>

<reference anchor="OIDCUAR" target="https://openid.net/specs/openid-connect-unmet-authentication-requirements-1_0.html">
  <front>
    <title>OpenID Connect Core Error Code unmet_authentication_requirements</title>
    <author fullname="Torsten Lodderstedt" initials="T." surname="Lodderstedt">
      <organization>YES</organization>
    </author>
    <date year="2019" month="May" day="8"/>
  </front>
</reference>

<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7662.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8414.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9068.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9110.xml"/>
</references>
</references>

<section anchor="Acknowledgements"><name>Acknowledgements</name> anchor="Acknowledgements" numbered="false"><name>Acknowledgements</name>
<t>I wanted to thank the Academy, the viewers at home, the shampoo manufacturers, etc..</t> etc.</t>
<t>This specification was developed within the OAuth Working Group under the
chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig <contact fullname="Rifaat Shekh-Yusef"/> and <contact
fullname="Hannes Tschofenig"/> with
Paul Wouters, and Roman Danyliw <contact fullname="Paul Wouters"/> and
<contact fullname="Roman Danyliw"/> serving as Security Area
Directors. Additionally, the following individuals contributed ideas,
feedback, corrections, and wording that helped shape this specification:
Caleb Baker,
Ivan Kanakarakis,
Pieter Kasselman,
Aaron Parecki,
Denis Pinkas,
Dima Postnikov,
and
Filip Skokan.</t>
<contact fullname="Caleb Baker"/>, <contact fullname="Ivan Kanakarakis"/>,
<contact fullname="Pieter Kasselman"/>, <contact fullname="Aaron Parecki"/>,
<contact fullname="Denis Pinkas"/>, <contact fullname="Dima Postnikov"/>, and
<contact fullname="Filip Skokan"/>.</t>
<t>Some early discussion of the motivations and concepts that precipitated the
initial draft version of this document occurred at the 2021 OAuth Security
Workshop. The authors thank the organizers of the workshop (Guido Schmitz, Steinar Noem, and Daniel Fett) (<contact
fullname="Guido Schmitz"/>, <contact fullname="Steinar Noem"/>, and <contact
fullname="Daniel Fett"/>) for hosting an event that is conducive to
collaboration and community input.</t>
</section>

<section anchor="document-history"><name>Document History</name>
<t>[[ To be removed from the final specification ]]</t>
<t>-17</t>

<ul>
<li>Fix mistake in -16 update</li>
</ul>
<t>-16</t>

<ul>
<li>AD suggested editorial updates</li>
</ul>
<t>-15</t>

<ul>
<li>Editorial updates from IESG review/ballot</li>
</ul>
<t>-14</t>

<ul>
<li>Updates from Httpdir telechat review</li>
</ul>
<t>-13</t>

<ul>
<li>Make IETF the Change Controller for all registration requests per IANA suggestion</li>
<li>More updates from Genart review</li>
<li>Updates from Artart review</li>
<li>Updates from Secdir review</li>
</ul>
<t>-12</t>

<ul>
<li>Updates from Genart Last Call review</li>
</ul>
<t>-11</t>

<ul>
<li>Updates in the Protocol Overview section clarifying the nature of "authentication levels" and caching strategies, addressing AD review comments</li>
</ul>
<t>-10</t>

<ul>
<li>Fix two references where the section numbers got lost presumably due to tooling issues</li>
</ul>
<t>-09</t>

<ul>
<li>Updates addressing AD review comments</li>
</ul>
<t>-07/-08</t>

<ul>
<li>Editorial updates addressing Shepherd Review comments</li>
</ul>
<t>-06</t>

<ul>
<li>Update examples/figures to be clear that the authorization request is sent by the client via directing the user agent (not directly from client to AS)</li>
</ul>
<t>-05</t>

<ul>
<li>Forgotten Acknowledgements</li>
<li>Minor updates to the updates in -04</li>
</ul>
<t>-04</t>

<ul>
<li>Editorial updates/notes from WGLC feedback</li>
</ul>
<t>-03</t>

<ul>
<li>Clarified that <tt>acr_values</tt> and <tt>max_age</tt> can co-occur in the challenge when necessary</li>
<li>fleshed out deployment and security considerations</li>
<li>fleshed out IANA considerations</li>
<li>Attempt to clarify that while <tt>acr_values</tt> can request more than one value, only one of them is used and ends up in the token</li>
</ul>
<t>-02</t>

<ul>
<li>Fix typos introduced in -01</li>
<li>Begin to fill out the Acknowledgements</li>
</ul>
<t>-01</t>

<ul>
<li>Added AS Metadata section with pointer to <tt>acr_values_supported</tt></li>
<li>Mention that it's not necessarily the case that a new 'stepped-up' token always supersedes older tokens</li>
<li>Add examples with <tt>max_age</tt></li>
</ul>
<t>-00 (Working Group Draft)</t>

<ul>
<li>Initial WG revision (content unchanged from draft-bertocci-oauth-step-up-authn-challenge-01)</li>
</ul>
<t>-01 draft-bertocci-oauth-step-up-authn-challenge</t>

<ul>
<li>Fixed example</li>
<li>Clarified/noted that scope can also be in the WWW-Authenticate/401</li>
</ul>
<t>-00 draft-bertocci-oauth-step-up-authn-challenge</t>

<ul>
<li>Initial Individual Draft (with all the authority thereby bestowed <eref target="https://datatracker.ietf.org/doc/html/draft-abr-twitter-reply">https://datatracker.ietf.org/doc/html/draft-abr-twitter-reply</eref>).</li>
</ul>
</section>
</back>
</rfc>