]> Okta

aaron@parecki.com

Practical Identity LLC

george@practicalidentity.com

Defakto Security

pieter@defakto.security

Security Web Authorization Protocol native apps first-party oauth This document defines the Authorization Challenge Endpoint, which supports clients that want to control the process of obtaining authorization from the user using a native experience. In many cases, this can provide an entirely browserless OAuth 2.0 experience suited for native applications, only delegating to the browser in unexpected, high-risk, or error conditions. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction This document, OAuth for First-Party Apps (FiPA), extends the OAuth 2.0 Authorization Framework with a new endpoint to support applications that want to control the process of obtaining authorization from the user using a native experience, with browser redirection as described in OAuth 2.0 for Native Apps used only as a fallback when needed. The client collects any initial information from the user and POSTs that information as well as information about the client's request to the Authorization Challenge Endpoint, and receives either an authorization code, as defined in , or an error code in response. The error code may indicate that the client can continue to prompt the user for more information, or can indicate that the client needs to launch a browser to have the user complete the flow in a browser. The Authorization Challenge Endpoint is used to initiate the OAuth flow in place of redirecting or launching a browser to the authorization endpoint. While a fully delegated approach using the redirect-based Authorization Code grant is generally preferred, this draft provides a mechanism for the client to directly interact with the user. This requires a high degree of trust between the authorization server and the client, as there typically is for first-party applications. It should be considered only when a redirect-based approach introduces usability issues, for example, when switching context between a native application and the browser disrupts the user journey and prevents task completion. This draft also extends the token response (typically for use in response to a refresh token request) and resource server response to allow the authorization server or resource server to indicate that the client should re-request authorization from the user. This can include requesting step-up authentication by including parameters defined in as well.

Usage and Applicability This specification is designed for the security model of first-party applications. First-party applications are applications that are controlled by the same entity as the authorization server and that users understand as belonging to the same entity. This specification is designed to be used by first-party native applications, which includes both mobile and desktop applications. Profiles of this specification that extend the usage to non-first-party use cases MUST describe how their application of this specification avoids the risks associated with third-party apps directly interacting with the user. For example, an extension of this specification that enables federation between native apps does not ask any third-party app to collect credentials from the user, so avoids these risks. Using this specification in scenarios other than those described may lead to unintended security and privacy problems for users and service providers. If a service provides multiple apps, and expects users to use multiple apps on the same device, there may be better ways of sharing a user's login between the apps other than each app implementing this specification or using an SDK that implements this specification. For example, provides a mechanism for one app to obtain new tokens by exchanging tokens from another app, without any user interaction. See for more details. Please review the entirety of , and when more than one first-party application is supported, .

Limitations of this specification This draft defines the overall framework for delivering a native OAuth user authentication experience. The precise client–server interactions used to authenticate the user (e.g., prompts, challenges, and step sequencing) are intentionally left to individual deployments and are out of scope for this specification. This specification is intended to be profiled to standardize specific interaction patterns enabling a complete interoperable solution.

User Experience Considerations It is important to consider the user experience implications of different authentication challenges as well as the device with which the user is attempting to authorize. For example, requesting a user to enter a password on a limited-input device (e.g., a TV) creates a lot of user friction while also exposing the user's password to anyone else in the room. On the other hand, a challenge method that uses, for example, a fingerprint reader on the TV remote for FIDO2 passkey authentication would be a good experience. The Authorization Server SHOULD consider the user's device when presenting authentication challenges and developers SHOULD consider whether the device implementing this specification can provide a good experience for the user. If the combination of user device and authentication challenge methods creates a lot of friction or security risk, consider using a specification like OAuth 2.0 Device Authorization Grant . If the OAuth 2.0 Device Authorization Grant is selected, which uses a cross-device authorization mechanism, please incorporate the security best practices identified in Cross-Device Flows: Security Best Current Practice . This specification also allows for the Authorization Server (AS) to direct the user to a browser-based authorization experience if the AS is not able to authorize the user via the requesting client app. This "redirect-to-web" experience is necessary to allow the AS to manage the security and privacy risks associated with any specific authorization requested by the user's client.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Server" (AS), "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server" (RS) and "Token Endpoint" defined by . TODO: Replace RFC6749 references with OAuth 2.1

Protocol Overview There are three primary ways this specification extends various parts of an OAuth system.

Initial Authorization Request || Authorization || Starts| | Party | || Challenge || Flow +-->| Client |<----------------------|| Endpoint || | | (C)Authorization || || | | Error Response || || | | : || || | | : || || | | (D)Authorization || || | | Challenge Request || || | |---------------------->|| || | | || || | |<----------------------|| || | | (E) Authorization |+-----------------+| | | Code Response | | | | | | | | | | | | | | | | (F) Token | | | | Request |+-----------------+| | |---------------------->|| Token || | | || Endpoint || | |<----------------------|| || | | (G) Access Token |+-----------------+| | | | | +----------+ +-------------------+ ]]> Figure: First-Party Client Authorization Code Request

• (A) The first-party client starts the flow by presenting the user with a "sign in" button or collecting information from the user, such as their email address or username (see ).
• (B) The client initiates the authorization request by making a POST request to the Authorization Challenge Endpoint (see ), optionally with information collected from the user (e.g., email or username).
• (C) The authorization server determines whether the information provided to the Authorization Challenge Endpoint is sufficient to grant authorization, and either responds with an authorization code or responds with an error (see ). In this example, it determines that additional information is needed and responds with an error. The error may contain additional information to guide the client on what information to collect next. This pattern of collecting information, submitting it to the Authorization Challenge Endpoint, and then receiving an error or authorization code may repeat several times.
• (D) The client gathers additional information (e.g., signed passkey challenge, or one-time code from email) and makes a POST request to the Authorization Challenge Endpoint.
• (E) The Authorization Challenge Endpoint returns an authorization code.
• (F) The client sends the authorization code received in step (E) to obtain a token from the Token Endpoint (see ).
• (G) The Authorization Server returns an Access Token from the Token Endpoint.

Refresh Token Request When the client uses a refresh token to obtain a new access token, the authorization server MAY respond with an error to indicate that re-authentication of the user is required.

Resource Request When making a resource request to a resource server, the resource server MAY respond with an error according to OAuth 2.0 Step-Up Authentication Challenge Protocol , indicating that re-authentication of the user is required. The use of in this specification is for interoperability with its defined error signaling and does not propose changes to itself.

Protocol Endpoints

Authorization Challenge Endpoint The authorization challenge endpoint is a new endpoint defined by this specification that the first-party application uses to obtain an authorization code. The authorization challenge endpoint is an HTTP API at the authorization server that accepts HTTP POST requests with parameters in the HTTP request message body using the application/x-www-form-urlencoded format. This format has a character encoding of UTF-8, as described in . The authorization challenge endpoint URL MUST use the "https" scheme. If the authorization server requires client authentication for this client at the Token Endpoint, then the authorization server MUST also require client authentication for this client at the Authorization Challenge Endpoint. See for more details. Authorization servers supporting this specification SHOULD include the URL of their authorization challenge endpoint in their authorization server metadata document using the authorization_challenge_endpoint parameter as defined in . The authorization challenge endpoint MUST accept the authorization request parameters as defined in for the authorization endpoint as well as any authorization endpoint extensions supported by the authorization server. Examples of such extensions include Proof Key for Code Exchange (PKCE) , Resource Indicators , and OpenID Connect . Note that some extension parameters have meaning in a web context but do not have meaning in a native mechanism (e.g., response_mode=query). How the authorization server handles an extension parameter that has no meaning in this use case is out of scope. The client initiates the authorization flow with or without information collected from the user (e.g. a signed passkey challenge or MFA code). The authorization challenge endpoint response is either an authorization code or an error code, and may also contain an auth_session which the client uses on subsequent requests. Further communication between the client and authorization server MAY happen at the Authorization Challenge Endpoint or any other proprietary endpoints at the authorization server.

Token endpoint The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token, as described in . This specification extends the token endpoint response to allow the authorization server to indicate that further authentication of the user is required.

Authorization Initiation A client may wish to initiate an authorization flow by first prompting the user for their user identifier or other account information. The authorization challenge endpoint is a new endpoint to collect this login hint and direct the client with the next steps, such as performing an MFA flow or an OAuth redirect-based flow. If the authorization server directs the client to complete the flow using a redirect-based authorization request in a browser, the client and authorization server SHOULD follow applicable best current practices for native apps (e.g., and its successors) for redirect URI selection and external user-agent usage. To preserve the security of this specification, the Authorization Server MUST verify the "first-partyness" of the client before continuing with the authentication flow. Please see for additional considerations.

Authorization Challenge Request The client makes a request to the authorization challenge endpoint by adding the following parameters, as well as parameters from any extensions, using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request body:

"client_id":

REQUIRED, unless the client is authenticating to the authorization server in a manner that unambiguously identifies the client, or the request includes an auth_session value associated with an existing session from which the authorization server can determine the client identity. The client MAY include the client_id even when one of these conditions applies. If it does, the authorization server MUST verify that the client_id identifies the same client as otherwise determined for the request, and MUST reject the request if it does not.

"scope":

OPTIONAL. The OAuth scope defined in .

"auth_session":

OPTIONAL. If the client has previously obtained an auth session, described in .

"code_challenge":

OPTIONAL. The code challenge as defined by . See for details.

"code_challenge_method":

OPTIONAL. The code challenge method as defined by . See for details.

"response_type":

REQUIRED. Per , response_type is required, and for this specification MUST contain the value of code.

Specific implementations as well as extensions to this specification MAY define additional parameters to be used at this endpoint. For example, the client makes the following request to initiate a flow given the user's phone number, line breaks shown for illustration purposes only:

Authorization Challenge Response The authorization server determines whether the information provided up to this point is sufficient to issue an authorization code, and if so responds with an authorization code. If the information is not sufficient for issuing an authorization code, then the authorization server MUST respond with an error response.

Authorization Code Response The authorization server issues an authorization code by creating HTTP response content using the application/json media type as defined by with the following parameters and an HTTP 200 (OK) status code:

"authorization_code":

REQUIRED. The authorization code issued by the authorization server.

For example,

Error Response If the request contains invalid parameters or incorrect data, or if the authorization server wishes to interact with the user directly, the authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise by a particular error code) and includes the following parameters with the response. Response parameters error, error_description, and error_uri are defined and used according to . request_uri and expires_in are defined and used according to . This specification defines the auth_session response parameter.

"error":

REQUIRED. A single ASCII error code as described in . Values for the error parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. The authorization server MAY extend these error codes with custom messages based on the requirements of the authorization server.

"error_description":

OPTIONAL. Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the error_description parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

"error_uri":

OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the error_uri parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.

"auth_session":

OPTIONAL. The auth session allows the authorization server to associate subsequent requests by this client with an ongoing authorization request sequence. The client MUST include the auth_session in follow-up requests to the authorization challenge endpoint if it receives one along with the error response.

"request_uri":

OPTIONAL. A request URI as described by .

"expires_in":

OPTIONAL. The lifetime of the request_uri in seconds, as described by .

This specification requires the authorization server to define new error codes that relate to the actions the client must take in order to properly authenticate the user. These new error codes are specific to the authorization server's implementation of this specification and are intentionally left out of scope. The parameters are included in the content of the HTTP response using the application/json media type as defined by . The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary. The authorization server MAY define additional parameters in the response depending on the implementation. The authorization server MAY also define more specific content types for the error responses as long as the response is JSON and conforms to application/<AS-defined>+json.

Error Codes This specification supports the use of error codes defined by and other error codes defined by OAuth extensions supported by the authorization server. This specification defines the following error codes. invalid_session: : The provided auth_session is invalid, expired, revoked, or otherwise not acceptable. insufficient_authorization: : The presented authorization is insufficient, and the authorization server is requesting the client to take additional steps to complete the authorization. The authorization server MUST respond with the HTTP 403 (Forbidden) status code. redirect_to_web: : The request is not able to be fulfilled with any further direct interaction with the user. Instead, the client should initiate a new authorization code flow so that the user interacts with the authorization server in a web browser. See for details. The authorization server MUST respond with the HTTP 403 (Forbidden) status code.

Redirect to Web Error Response The authorization server may choose to interact directly with the user based on a risk assessment, the introduction of a new authentication method not supported in the application, or to handle an exception flow such as account recovery. To indicate this error to the client, the authorization server returns an error response as defined above with the redirect_to_web error code. The response MAY include a request_uri, in which case the client is expected to use it to initiate an authorization request as described in . An example of the response including a request_uri is given below: If no request_uri is returned, the client is expected to initiate a new OAuth Authorization Code flow with PKCE according to and . If the client expects the frequency of this error response to be high, the client SHOULD include a PKCE code_challenge in the initial authorization challenge request. If the client does not include a PKCE code_challenge in the initial authorization challenge request, the authorization server MUST NOT return a request_uri in the redirect_to_web error response, as that would effectively be the same as a PAR request without PKCE. Clients and authorization servers using the redirect_to_web method SHOULD follow current best practices of redirect-based OAuth flows, especially those defined in , including mechanisms such as the iss response parameter defined in .

Intermediate Requests If the authorization server returns an insufficient_authorization error as described above, this is an indication that there is further information the client should request from the user, and continue to make requests to the authorization server until the authorization request is fulfilled and an authorization code returned. These intermediate requests are out of scope of this specification, and are expected to be defined by the authorization server. The format of these requests is not required to conform to the format of the initial authorization challenge requests (e.g. the request format may be application/json rather than application/x-www-form-urlencoded). These intermediate requests MAY also be sent to proprietary endpoints at the authorization server rather than the Authorization Challenge Endpoint.

Auth Session The auth_session is a value that the authorization server issues in order to be able to associate subsequent requests from the same client instance. It is intended to be analogous to how a browser cookie associates multiple requests by the same browser to the authorization server. The auth_session value is completely opaque to the client, and as such the authorization server MUST adequately protect the value from inspection by the client. If the client has an auth_session, the client MUST include it in future requests to the authorization challenge endpoint. The client MUST store the auth_session beyond the issuance of the authorization code to be able to use it in future requests. Every response defined by this specification may include a new auth_session value. Clients MUST NOT assume that auth_session values are static, and MUST be prepared to update the stored auth_session value if one is received in a response. Clients SHOULD discard the auth_session when the user logs out of the app. To mitigate the risk of session hijacking, the auth_session SHOULD be bound to the device, and the authorization server SHOULD reject an auth_session if it is presented from a different device than the one it was bound to. One method of binding the auth_session to the device is described in . The AS MUST ensure that the auth_session value is unique to the session and protected from accidental collisions. For example, if the AS is using a random string for the auth_session value, the value SHOULD have a minimum of 256 bits of entropy. See for additional security considerations.

Token Request The client makes a request to the token endpoint using the authorization code it obtained from the authorization challenge endpoint. This specification does not define any additional parameters beyond the token request parameters defined in . However, notably, the redirect_uri parameter will not be included in this request, because no redirect_uri parameter was included in the authorization request.

Token Endpoint Successful Response This specification extends the OAuth 2.0 token response defined in with the additional parameter auth_session, defined in . An example successful token response is below: The response MAY include an auth_session parameter which the client is expected to include on any subsequent requests to the authorization challenge endpoint, as described in . The auth_session parameter MAY also be included even if the authorization code was obtained through a traditional OAuth authorization code flow rather than the flow defined by this specification. The auth_session mechanism described in is an optional feature the authorization server can leverage in order to enable flows such as step-up authentication , so that the authorization server can restore the context of a previous session and prompt only for the needed step-up factors. See for an example application.

Token Endpoint Error Response Upon any request to the token endpoint, including a request with a valid refresh token, the authorization server can respond with an authorization challenge instead of a successful access token response. An authorization challenge error response is a particular type of error response as defined in where the error code is set to the following value:

"error": "insufficient_authorization":

The presented authorization is insufficient, and the authorization server is requesting that the client take additional steps to complete the authorization.

The response MAY also contain an auth_session parameter which the client is expected to include on a subsequent request to the authorization challenge endpoint.

"auth_session":

OPTIONAL. The optional auth session value allows the authorization server to associate subsequent requests by this client with an ongoing authorization request sequence. The client MUST include the auth_session in follow-up requests to the challenge endpoint if it receives one along with the error response.

Additionally, the response MAY contain custom values that describe instructions for how the client should proceed to interact with the user. For example:

Resource Server Error Response Step-Up Authentication defines error code values that a resource server can use to tell the client to start a new authorization request including acr_values and max_age from . This specification reuses the Step-Up Authentication error response to initiate a first-party authorization flow to satisfy the step-up authentication request. Upon receiving this error response, the client starts a new first-party authorization request at the authorization challenge endpoint, and includes the acr_values, max_age and scope that were returned in the error response. This specification does not update or alter resource server error behavior and does not define any new parameters for the resource server error response beyond those defined in and . It only defines first-party client behavior for continuing authorization at the authorization challenge endpoint when such an error is received.

Authorization Server Metadata The following authorization server metadata parameters are introduced to signal the server's capability and policy with respect to first-party applications.

"authorization_challenge_endpoint":

The URL of the authorization challenge endpoint at which a client can initiate an authorization request and eventually obtain an authorization code.

Security Considerations

First-Party Applications First-party applications are applications that are controlled by the same entity as the authorization server used by the application, and that users understand as belonging to the same entity. For first-party applications, it is important that the user recognizes the application and authorization server as belonging to the same brand. For example, a bank publishing their own mobile application. Because this specification enables a client application to interact directly with the end user, and the application handles sending any information collected from the user to the authorization server, it is expected to be used only for first-party applications when the authorization server also has a high degree of trust of the client. This specification is not prescriptive on how the Authorization Server establishes its trust in the first-partyness of the application. For mobile platforms, most support some mechanism for application attestation that can be used to identify the entity that created/signed/uploaded the app to the app store. App attestation can be combined with mechanisms such as Attestation-Based Client Authentication or Dynamic Client Registration to enable strong client authentication in addition to client verification (first-partyness). The exact steps required are out of scope for this specification. Note that for applications running inside a browser context (e.g., Single Page Apps), it is much more difficult to verify the first-partyness of the client. Please see for additional details.

Phishing There are two ways using this specification increases the risk of phishing.

1. Malicious application: With this specification, the client interacts directly with the end user, collecting information provided by the user and sending it to the authorization server. If an attacker impersonates the client and successfully tricks a user into using it, they may not realize they are giving their credentials to the malicious application.
2. User education: In a traditional OAuth deployment using the redirect-based authorization code flow, the user will only ever enter their credentials at the authorization server, and it is straightforward to explain to avoid entering credentials in other "fake" websites. By introducing a new place the user is expected to enter their credentials using this specification, it is more complicated to teach users how to recognize other fake login prompts that might be attempting to steal their credentials.

Because of these risks, the authorization server MAY decide to require that the user go through a redirect-based flow at any stage of the process based on its own risk assessment.

Credential Stuffing Attacks The authorization challenge endpoint is capable of directly receiving user credentials and other authentication material like OTPs. This exposes a new vector to perform credential stuffing or brute force attacks if additional measures are not taken to ensure the authenticity of the application. An authorization server may already have a combination of built-in or third-party security tools in place to monitor and reduce this risk in browser-based authentication flows. Implementors SHOULD consider similar security measures to reduce this risk in the authorization challenge endpoint. Additionally, the attestation APIs SHOULD be used when possible to assert a level of confidence to the authorization server that the request is originating from an application owned by the same party. Implementors SHOULD rate-limit requests from the same auth_session.

Client Authentication Typically, mobile and desktop applications are considered "public clients" in OAuth, since they cannot be shipped with a statically configured set of client credentials . Because of this, client impersonation should be a concern of anyone deploying this pattern. Without client authentication, a malicious user or attacker can mimic the requests the application makes to the authorization server, pretending to be the legitimate client. Implementers SHOULD consider additional measures to limit the risk of client impersonation, such as using attestation APIs available from the operating system.

Sender-Constrained Tokens Tokens issued in response to an authorization challenge request SHOULD be sender-constrained to mitigate the risk of token theft and replay. Proof-of-Possession techniques constrain tokens by binding them to a cryptographic key. Whenever the token is presented, it MUST be accompanied by a proof that the client presenting the token also controls the cryptographic key bound to the token. If a proof-of-possession sender-constrained token is presented without valid proof of possession of the cryptographic key, it MUST be rejected.

DPoP: Demonstrating Proof-of-Possession DPoP is an application-level mechanism for sender-constraining OAuth access and refresh tokens. If DPoP is used to sender constrain tokens, the client SHOULD use DPoP for every token request to the Authorization Server and interaction with the Resource Server. DPoP includes an optional capability to bind the authorization code to the DPoP key to enable end-to-end binding of the entire authorization flow. Given the back-channel nature of this specification, there are far fewer opportunities for an attacker to access the authorization code and PKCE code verifier compared to the redirect-based Authorization Code Flow. In this specification, the Authorization Code is obtained via a back-channel request. Despite this, omitting Authorization Code binding leaves a gap in the end-to-end protection that DPoP provides, so DPoP Authorization Code binding SHOULD be used. The mechanism for Authorization Code binding with DPoP is similar to that defined for Pushed Authorization Requests (PARs) in . In order to bind the Authorization Code with DPoP, the client MUST add the DPoP header to the Authorization Challenge Request. The authorization server MUST check the DPoP proof JWT that was included in the DPoP header as defined in . The authorization server MUST ensure that the same key is used in all subsequent Authorization Challenge Requests and in the eventual token request. The authorization server MUST reject subsequent Authorization Challenge Requests, or the eventual token request, unless a DPoP proof for the same key presented in the original Authorization Challenge Request is provided. The above mechanism simplifies the implementation of the client, as it can attach the DPoP header to all requests to the authorization server regardless of the type of request. This mechanism provides a stronger binding than using the dpop_jkt parameter, as the DPoP header contains a proof of possession of the private key.

Other Proof of Possession Mechanisms It may be possible to use other proof-of-possession mechanisms to sender-constrain access and refresh tokens. Defining these mechanisms is out of scope for this specification.

Auth Session Binding the auth_session to the device requesting authorization is important to prevent session hijacking and replay of the auth_session value. Without the device binding a captured auth_session could be replayed from another device. The following section describes one way to bind the auth_session to the requesting device. Other device binding methods are available and usable to prevent this potential security exposure.

Auth Session DPoP Binding If the client and authorization server are using DPoP binding of access tokens and/or authorization codes, then the auth_session value SHOULD be protected as well. The authorization server SHOULD associate the auth_session value with the DPoP public key. This removes the need for the authorization server to include additional claims in the DPoP proof, while still benefitting from the assurance that the client presenting the proof has control over the DPoP key. To associate the auth_session value with the DPoP public key, the authorization server:

• MUST check that the same DPoP public key is being used when the client presents the DPoP proof.
• MUST verify the DPoP proof to ensure the client controls the corresponding private key whenever the client includes the auth_session in an Authorization Challenge Request as described in .

DPoP binding of the auth_session value ensures that the context referenced by the auth_session cannot be stolen and reused by another device.

Auth Session Lifetime This specification makes no requirements or assumptions on the lifetime of the auth_session value. The lifetime and expiration is at the discretion of the authorization server, and the authorization server may choose to invalidate the value for any reason such as scheduled expiration, security events, or revocation events. Clients MUST NOT make any assumptions or depend on any particular lifetime of the auth_session value.

Multiple Applications When multiple first-party applications are supported by the AS, then it is important to consider a number of additional risks. These risks fall into two main categories: experience risk and technical risk, which are described below.

User Experience Risk Any time a user is asked to provide the authentication credentials in user experiences that differ, it has the effect of increasing the likelihood that the user will fall prey to a phishing attack because they are used to entering credentials in different looking experiences. When multiple first-party applications are supported, the implementation MUST ensure the native experience is identical across all the first-party applications. Another experience risk is user confusion caused by different looking experiences and behaviors. This can increase the likelihood the user will not complete the authentication experience for the first-party application.

Technical Risk In addition to the experience risks, multiple implementations in first-party applications increase the risk of an incorrect implementation as well as increasing the attack surface as each implementation may expose its own weaknesses.

Mitigation To address these risks, when multiple first-party applications must be supported, and other methods such as are not applicable, it is RECOMMENDED that a client-side SDK be used to ensure the implementation is consistent across the different applications and to ensure the user experience is identical for all first-party apps.

Single Page Applications Single Page Applications (SPAs) run in a scripting language inside the context of a browser instance. This environment poses several unique challenges compared to native applications, in particular:

• Significant attack vectors due to the possibility of Cross-Site Scripting (XSS) attacks
• Fewer options to securely attest to the first-partyness of a browser-based application

See for a detailed discussion of the risks of XSS attacks in browsers. Additionally, the nature of a Single-Page App means the user is already in a browser context, so the user experience cost of doing a full-page redirect or a popup window for the traditional OAuth Authorization Code Flow is much less than the cost of doing so in a native application. The complexity and risk of implementing this specification in a browser likely does not outweigh the user experience benefits that would be gained in that context. For these reasons, it is NOT RECOMMENDED to use this specification in browser-based applications.

IANA Considerations

OAuth Parameters Registration IANA has (TBD) registered the following values in the IANA "OAuth Parameters" registry of established by . Parameter name: auth_session Parameter usage location: token response Change Controller: IETF Specification Document: of this document

OAuth Server Metadata Registration IANA has (TBD) registered the following values in the IANA "OAuth Authorization Server Metadata" registry of established by . Metadata Name: authorization_challenge_endpoint Metadata Description: URL of the authorization server's authorization challenge endpoint. Change Controller: IESG Specification Document: of this document

References Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange (PKCE, pronounced "pixy"). JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. The OAuth 2.0 device authorization grant is designed for Internet- connected devices that either lack a browser to perform a user-agent- based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables OAuth clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorization to access protected resources by using a user agent on a separate device. This document specifies an extension to the OAuth 2.0 Authorization Framework defining request parameters that enable a client to explicitly signal to an authorization server about the identity of the protected resource(s) to which it is requesting access. This document defines the pushed authorization request (PAR) endpoint, which allows clients to push the payload of an OAuth 2.0 authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint. This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. 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 that resource 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, 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. Defakto Security Authlete Okta This document describes threats against cross-device flows along with practical mitigations, protocol selection guidance, and a summary of formal analysis results identified as relevant to the security of cross-device flows. It serves as a security guide to system designers, architects, product managers, security specialists, fraud analysts and engineers implementing cross-device flows. IANA In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] OAuth 2.0 authorization requests from native apps should only be made through external user-agents, primarily the user's browser. This specification details the security and usability reasons why this is the case and how native apps and authorization servers can implement this best practice. This document describes best current security practice for OAuth 2.0. It updates and extends the threat model and security advice given in RFCs 6749, 6750, and 6819 to incorporate practical experiences gathered since OAuth 2.0 was published and covers new threats relevant due to the broader application of OAuth 2.0. Further, it deprecates some modes of operation that are deemed less secure or even insecure. This document specifies a new parameter called iss. This parameter is used to explicitly include the issuer identifier of the authorization server in the authorization response of an OAuth authorization flow. The iss parameter serves as an effective countermeasure to "mix-up attacks". Okta Pragmatic Web Security Ping Identity This specification details the threats, attack consequences, security considerations and best practices that must be taken into account when developing browser-based applications that use OAuth 2.0. Discussion Venues This note is to be removed before publishing as an RFC. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Source for this draft and an issue tracker can be found at https://github.com/oauth-wg/oauth-browser-based-apps. MATTR Bundesdruckerei SPRIND This specification defines an extension to the OAuth 2.0 protocol [RFC6749] that enables a client instance to include a key-bound attestation when interacting with an Authorization Server or Resource Server. This mechanism allows a client instance to prove its authenticity verified by a client attester without revealing its target audience to that attester. It may also serve as a mechanism for client authentication as per OAuth 2.0.

Example User Experiences This section provides non-normative examples of how this specification may be used to support specific use cases.

Passkey A user may log in with a passkey (without a password).

1. The Client collects the username from the user.
2. The Client sends an Authorization Challenge Request () to the Authorization Challenge Endpoint () including the username.
3. The Authorization Server verifies the username and returns a challenge.
4. The user is prompted for verification with biometrics or a PIN, enabling the Client to sign the challenge using the passkey.
5. The Client sends the signed challenge, username, and credential ID to the Authorization Challenge Endpoint ().
6. The Authorization Server verifies the signed challenge and returns an Authorization Code.
7. The Client requests an Access Token and Refresh Token by issuing a Token Request () to the Token Endpoint.
8. The Authorization Server verifies the Authorization Code and issues the requested tokens.

Redirect to Authorization Server A user may be redirected to the Authorization Server to perform an account reset.

1. The Client collects a username from the user.
2. The Client sends an Authorization Challenge Request () to the Authorization Challenge Endpoint () including the username.
3. The Authorization Server verifies the username and determines that the account is locked and returns a Redirect error response.
4. The Client parses the redirect message, opens a browser, and redirects the user to the Authorization Server to perform an OAuth 2.0 flow with PKCE.
5. The user resets their account by performing a multi-step authentication flow with the Authorization Server.
6. The Authorization Server issues an Authorization Code in a redirect back to the client, which then exchanges it for an access and refresh token.

Passwordless One-Time Password (OTP) In a passwordless One-Time Password (OTP) scheme, the user is in possession of a one-time password generator. This generator may be a hardware device, or implemented as an app on a mobile phone. The user provides a user identifier and one-time password, which is verified by the Authorization Server before it issues an Authorization Code, which can be exchanged for an Access and Refresh Token.

1. The Client collects a username and OTP from the user.
2. The Client sends an Authorization Challenge Request () to the Authorization Challenge Endpoint () including the username and OTP.
3. The Authorization Server verifies the username and OTP and returns an Authorization Code.
4. The Client requests an Access Token and Refresh Token by issuing a Token Request () to the Token Endpoint.
5. The Authorization Server verifies the Authorization Code and issues the requested tokens.

Email Confirmation Code A user may be required to provide an email confirmation code as part of an authentication ceremony to prove they control an email address. The user provides an email address and is then required to enter a verification code sent to the email address. If the correct verification code is returned to the Authorization Server, it issues Access and Refresh Tokens.

1. The Client collects an email address from the user.
2. The Client sends the email address in an Authorization Challenge Request () to the Authorization Challenge Endpoint ().
3. The Authorization Server sends a verification code to the email address and returns an Error Response () including "error": "insufficient_authorization", "auth_session" and a custom property indicating that an email verification code must be entered.
4. The Client presents a user experience guiding the user to copy the email verification code to the Client. Once the email verification code is entered, the Client sends an Authorization Challenge Request to the Authorization Challenge Endpoint, including the email verification code as well as the auth_session parameter returned in the previous Error Response.
5. The Authorization Server uses the auth_session to maintain the session and verifies the email verification code before issuing an Authorization Code to the Client.
6. The Client sends the Authorization Code in a Token Request () to the Token Endpoint.
7. The Authorization Server verifies the Authorization Code and issues the Access Token and Refresh Token.

An alternative version of this verification involves the user clicking a link in an email rather than manually entering a verification code. This is typically done for email verification flows rather than inline in a login flow. The protocol-level details remain the same for the alternative flow despite the different user experience. All steps except step 4 above remain the same, but the client presents an alternative user experience for step 4 described below:

• The Client presents a message to the user instructing them to click the link sent to their email address. The user clicks the link in the email, which contains the verification code in the URL. The URL launches the app providing the verification code to the Client. The Client sends the verification code and auth_session to the Authorization Challenge Endpoint.

Mobile Confirmation Code A user may be required to provide a confirmation code as part of an authentication ceremony to prove they control a mobile phone number. The user provides a phone number and is then required to enter a confirmation code sent to the phone. If the correct confirmation code is returned to the Authorization Server, it issues Access and Refresh Tokens.

1. The Client collects a mobile phone number from the user.
2. The Client sends the phone number in an Authorization Challenge Request () to the Authorization Challenge Endpoint ().
3. The Authorization Server sends a confirmation code to the phone number and returns an Error Response () including "error": "insufficient_authorization", "auth_session" and a custom property indicating that a confirmation code must be entered.
4. The Client presents a user experience guiding the user to enter the confirmation code. Once the code is entered, the Client sends an Authorization Challenge Request to the Authorization Challenge Endpoint, including the confirmation code as well as the auth_session parameter returned in the previous Error Response.
5. The Authorization Server uses the auth_session to maintain the session context and verifies the code before issuing an Authorization Code to the Client.
6. The Client sends the Authorization Code in a Token Request () to the Token Endpoint.
7. The Authorization Server verifies the Authorization Code and issues the Access Token and Refresh Token.

Re-authenticating to an app a week later using OTP A client may be in possession of an Access and Refresh Token as the result of a previous successful user authentication. The user returns to the app a week later and accesses the app. The Client presents the Access Token, but receives an error indicating the Access Token is no longer valid. The Client presents a Refresh Token to the Authorization Server to obtain a new Access Token. If the Authorization Server requires user interaction for reasons based on its own policies, it rejects the Refresh Token and the Client re-starts the user authentication flow to obtain new Access and Refresh Tokens.

1. The Client has a short-lived access token and long-lived refresh token following a previous completion of an Authorization Grant Flow which included user authentication.
2. A week later, the user launches the app and tries to access a protected resource at the Resource Server.
3. The Resource Server responds with an error code indicating an invalid access token since it has expired.
4. The Client presents the refresh token to the Authorization Server to obtain a new access token ().
5. The Authorization Server responds with an error code indicating that an OTP from the user is required, as well as an auth_session.
6. The Client prompts the user to enter an OTP.
7. The Client sends the OTP and auth_session in an Authorization Challenge Request () to the Authorization Challenge Endpoint ().
8. The Authorization Server verifies the auth_session and OTP, and returns an Authorization Code.
9. The Client sends the Authorization Code in a Token Request () to the Token Endpoint.
10. The Authorization Server verifies the Authorization Code and issues the requested tokens.
11. The Client presents the new Access Token to the Resource Server in order to access the protected resource.

Step-up Authentication using Confirmation SMS A Client previously obtained an Access and Refresh Token after the user authenticated with an OTP. When the user attempts to access a protected resource, the Resource Server determines that it needs an additional level of authentication and triggers a step-up authentication, indicating the desired level of authentication using acr_values and max_age as defined in the Step-Up Authentication specification. The Client initiates an authorization request with the Authorization Server indicating the acr_values and max_age parameters. The Authorization Server responds with error messages prompting for additional authentication until the acr_values and max_age values are satisfied before issuing fresh Access and Refresh Tokens.

1. The Client has a short-lived access token and long-lived refresh token following the completion of an Authorization Code Grant Flow which included user authentication.
2. When the Client presents the Access Token to the Resource Server, the Resource Server determines that the acr claim in the Access Token is insufficient given the resource the user wants to access and responds with an insufficient_user_authentication error code, along with the desired acr_values and max_age.
3. The Client sends an Authorization Challenge Request () to the Authorization Challenge Endpoint () including the auth_session, acr_values and max_age parameters.
4. The Authorization Server verifies the auth_session and determines which authentication methods must be satisfied based on the acr_values, and responds with an Error Response () including "error": "insufficient_authorization" and a custom property indicating that an OTP must be entered.
5. The Client prompts the user for an OTP, which the user obtains and enters.
6. The Client sends an Authorization Challenge Request to the Authorization Challenge Endpoint including the auth_session and OTP.
7. The Authorization Server verifies the OTP and returns an Authorization Code.
8. The Client sends the Authorization Code in a Token Request () to the Token Endpoint.
9. The Authorization Server verifies the Authorization Code and issues an Access Token with the updated acr value along with the Refresh Token.
10. The Client presents the Access Token to the Resource Server, which verifies that the acr value meets its requirements before granting access to the protected resource.

Registration This example describes how to use the mechanisms defined in this draft to create a complete user registration flow starting with an email address. In this example, it is the Authorization Server's policy to allow these challenges to be sent to email addresses and phone numbers that were previously unrecognized, creating the user account on the fly.

1. The Client collects a username from the user.
2. The Client sends an Authorization Challenge Request () to the Authorization Challenge Endpoint () including the username.
3. The Authorization Server returns an Error Response () including "error": "insufficient_authorization", "auth_session", and a custom property indicating that an email address must be collected.
4. The Client collects an email address from the user.
5. The Client sends the email address as part of a second Authorization Challenge Request to the Authorization Challenge Endpoint, along with the auth_session parameter.
6. The Authorization Server sends a verification code to the email address and returns an Error Response including "error": "insufficient_authorization", "auth_session" and a custom property indicating that an email verification code must be entered.
7. The Client presents a user experience guiding the user to copy the email verification code to the Client. Once the email verification code is entered, the Client sends an Authorization Challenge Request to the Authorization Challenge Endpoint, including the email verification code as well as the auth_session parameter returned in the previous Error Response.
8. The Authorization Server uses the auth_session to maintain the session context, and verifies the email verification code. It determines that it also needs a phone number for account recovery purposes and returns an Error Response including "error": "insufficient_authorization", "auth_session" and a custom property indicating that a phone number must be collected.
9. The Client collects a mobile phone number from the user.
10. The Client sends the phone number in an Authorization Challenge Request to the Authorization Challenge Endpoint, along with the auth_session.
11. The Authorization Server uses the auth_session parameter to link the previous requests. It sends a confirmation code to the phone number and returns an Error Response including "error": "insufficient_authorization", "auth_session" and a custom property indicating that an SMS confirmation code must be entered.
12. The Client presents a user experience guiding the user to enter the SMS confirmation code. Once the SMS verification code is entered, the Client sends an Authorization Challenge Request to the Authorization Challenge Endpoint, including the confirmation code as well as the auth_session parameter returned in the previous Error Response.
13. The Authorization Server uses the auth_session to maintain the session context, and verifies the SMS verification code before issuing an Authorization Code to the Client.
14. The Client sends the Authorization Code in a Token Request () to the Token Endpoint.
15. The Authorization Server verifies the Authorization Code and issues the requested tokens.

Example Implementations To successfully implement this specification, the Authorization Server will need to define its own specific profile for what values clients are expected to send in the Authorization Challenge Request (), as well as AS-defined specific error codes in the Authorization Challenge Response (). It is expected that service providers will wrap the implementation of this specification in an SDK that will be used by application developers, removing the need for application developers to implement the specification themselves. Below is an example profile that allows for a successful implementation that enables the user to log in with a username and OTP. This example is included for illustration purposes only to help AS developers define the profile for their deployment and ecosystem.

Authorization Challenge Request Parameters In addition to the request parameters defined in , the authorization server defines the additional parameters below.

"username":

REQUIRED for the initial Authorization Challenge Request.

"otp":

The OTP collected from the user. REQUIRED when retrying an Authorization Challenge Request in response to the otp_required error defined below.

Authorization Challenge Response Parameters In addition to the response parameters defined in , the authorization server defines the additional parameter below.

"otp_required":

The client should collect an OTP from the user and send the OTP in a second request to the Authorization Challenge Endpoint.

Example Sequence - Initial Authorization The client prompts the user to enter their username, and sends the username in an initial Authorization Challenge Request. The Authorization Server sends an error response indicating that an OTP is required. The client prompts the user for an OTP, and sends a new Authorization Challenge Request. The Authorization Server validates the auth_session to find the expected user, then validates the OTP for that user, and responds with an authorization code. The client sends the authorization code to the token endpoint. The Authorization Server responds with an access token and refresh token.

Example Sequence - Refresh Token Request Triggering Additional Authorization This example illustrates the use case described in . The client sends a refresh token request to obtain a new access token. The Authorization Server determines that additional authorization is required (for example, step-up or re-verification) before the refresh token can be used, and returns an authorization challenge error response. The client prompts the user for an OTP, and sends an Authorization Challenge Request to continue the authorization session identified by auth_session. The Authorization Server validates the auth_session to find the expected user, then validates the OTP for that user, and responds with an authorization code. The client sends the authorization code to the token endpoint. The Authorization Server responds with an access token and new refresh token.

Design Goals This specification defines a new authorization flow the client can use to obtain an authorization grant. There are two primary reasons for designing the specification this way. This enables existing OAuth implementations to make fewer modifications to existing code by not needing to extend the token endpoint with new logic. Instead, the new logic can be encapsulated in an entirely new endpoint, the output of which is an authorization code which can be redeemed for an access token at the existing token endpoint. This also mirrors more closely the existing architecture of the redirect-based authorization code flow. In the authorization code flow, the client first initiates a request by redirecting a browser to the authorization endpoint, at which point the authorization server takes over with its own custom logic to authenticate the user in whatever way appropriate, possibly including interacting with other endpoints for the actual user authentication process. Afterwards, the authorization server redirects the user back to the client application with an authorization code in the query string. This specification mirrors the existing approach by having the client first make a POST request to the Authorization Challenge Endpoint, at which point the authorization server provides its own custom logic to authenticate the user, eventually returning an authorization code. An alternative design would be to define new custom grant types for the different authentication factors such as WebAuthn, OTP, etc. The drawback to this design is that conceptually, these authentication methods do not map to an OAuth grant. In other words, the OAuth authorization grant captures the user's intent to authorize access to some data, and that authorization is represented by an authorization code, not by different methods of authenticating the user. Another alternative option would be to have the Authorization Challenge Endpoint return an access token upon successful authentication of the user. This was deliberately not chosen, as this adds a new endpoint that tokens would be returned from. In most deployments, the Token Endpoint is the only endpoint that actually issues tokens, and includes all the implementation logic around token binding, rate limiting, etc. Instead of defining a new endpoint that issues tokens which would have to have similar logic and protections, instead the new endpoint only issues authorization codes, which can be exchanged for tokens at the existing Token Endpoint just like in the redirect-based Authorization Code flow. These design decisions should enable authorization server implementations to isolate and encapsulate the changes needed to support this specification.

Document History -04

• Editorial clarifications and improvements
• Updated HTTP response codes for consistency

-03

• Editorial clarifications and improvements
• Pointed definition of authorization code to section 1.3.1 of RFC 6749
• Updated auth_session binding requirements to SHOULD, and added a reference to DPoP
• Revised introduction and context to clarify this draft is intended for first-party applications but can be extended for third-party in some situations
• Added response_type=code as a required parameter to match RFC 6749

-02

• Updated affiliations and acks
• Editorial clarifications
• Added reference to Attestation-Based Client Authentication

-01

• Corrected "re-authorization of the user" to "re-authentication of the user"

-00

• Adopted into the OAuth WG, no changes from previous individual draft

Acknowledgments The authors would like to thank the attendees of the OAuth Security Workshop 2023 session in which this was discussed, as well as the following individuals who contributed ideas, feedback, and wording that shaped and formed the final specification: Alejo Fernandez, Brian Campbell, Dean Saxe, Dick Hardt, Dmitry Telegin, Evert Pot, Filip Skokan, Janak Amarasena, Jeff Corrigan, John Bradley, Joseph Heenan, Justin Richer, Kristina Yasuda, Martin Besozzi, Matt MacAdam, Mike Jones, Orie Steele, Tim Cappalli, Tobias Looker, Yaron Sheffer, Yaron Zehavi.