]> Okta

aaron@parecki.com https://aaronparecki.com

Security Web Authorization Protocol oauth delegation This specification defines a vocabulary and method of transmitting information about an OAuth client when a user is redirected through one or more authorization servers during an OAuth flow. This provides the deeper nested authorization servers with additional context that they can use for informational or revocation purposes. 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 In a typical OAuth flow, the OAuth client redirects the user agent to the authorization server where the user logs in and (optionally) approves the request. The OAuth framework describes the interaction between the Client, the Authorization Server, and the Resource Server. The interaction between the End-User and the Authorization Server, when the user logs in, is intentionally out of scope of OAuth. In practice, user authentication at the Authorization Server happens via a wide variety of methods, including simple username/password login, as well as redirecting to additional OAuth or OpenID Connect servers, such as when using consumer social login providers or enterprise identity providers. When user authentication happens via an external identity provider, it takes place as a brand new OAuth flow from the initial authorization server to the external identity provider. The initial authorizaiton server acts as an OAuth client to the external identity provider. Because this is a new flow, the context of the original OAuth flow is lost, and the external identity provider is unable to take actions or record information based on the actual OAuth client the End-User is using. This specification introduces a vocabulary and method of transmitting information about an OAuth client to an external identity provider when used in nested flows.

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", "End-User", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server" (RS) and "Token Endpoint" defined by , and the terms "OpenID Provider" (OP) and "ID Token" defined by . TODO: Replace RFC6749 references with OAuth 2.1 This specification defines the following terms:

"Application Class":

The type of application the End-User is logging in to, as defined by the AS in the first OAuth flow.

"Device":

The physical device the End-User is interacting with when authorizing a Client.

This specification uses the term "Identity Provider" (IdP) to refer to the Authorization Server or OpenID Provider that is used for End-User authentication.

Protocol Overview For the sake of simplicity, we will refer to the parties involved in the flow as:

• User Agent: The browser used by the End-User
• Client: The OAuth client that is being used by the End-User
• Authorization Server (AS): The authorization server the Client interacts with and is expecting to receive tokens from
• Identity Provider (IdP): The authorization server where the End-User has an account and logs in

(In practice, in the inner OAuth flow, the Authorization Server is acting as an OAuth Client to the Identity Provider.) TODO: Convert to ASCII art https://github.com/aaronpk/oauth-metadata-for-nested-flows/blob/main/nested-oauth-flow.svg

1. The OAuth Client initiates an OAuth flow by redirecting the User Agent to the Authorization Server.
2. The User Agent visits the Authorization Server.
3. The Authorization Server initiates a new OAuth flow as the OAuth client to the Identity Provider by redirecting the User Agent to the Identity Provider, and provides the additional parameters defined in .
4. The User Agent visits the Identity Provider.
5. The Identity Provider authenticates the End-User.
6. The Identity Provider issues an authorization code and redirects the User Agent back to the Authorization Server.
7. The User Agent visits the Authorization Server carrying the authorization code from the Identity Provider.
8. The Authorization Server exchanges the authorization code at the Identity Provider for an access token and optional ID token.
9. The Identity Provider responds with the tokens.
10. The Authorization Server consumes the tokens and issues its own authorization code, and redirects the User Agent back to the Client.
11. The User Agent visits the Client carrying the authorization code from the Authorization Server.
12. The Client exchanges the authorization code for an access token at the Authorization Server.
13. The Authorization Server responds with the tokens.

In this example, the two OAuth flows are authorization code flows. In practice, the inner flow can often be the OpenID Connect Implicit Flow (with response_type=id_token) where there is no intermediate authorization code issued. This distinction is not relevant to the rest of this specification. Either or both OAuth flows may also be using other OAuth extensions, such as Pushed Authorization Requests , JWT-Secured Authorization Request or others. While these extensions may change the example sequence above slightly, they do not fundamentally change the need for the additional context added by this specification. See for examples of how to provide the properties defined in this specification along with other OAuth extensions.

Parameters This specification introduces new parameters in the authorization request to the Identity Provider to indicate information about the downstream OAuth client:

"application_class_id":

An identifier for the Application Class, unique within the Authorization Server

"application_class_name":

A human-readable name describing the Application Class, e.g. "Chat App for iOS"

"device_id":

An identifier for the Device the End-User is using

"device_name":

A human-readable name describing the End-User's device, e.g. "Alice's iPhone"

"session_ref":

A reference to the End-User session at the OAuth Authorization Server. This MUST NOT be the actual session cookie. This identifier enables the IdP to identify a user's session.

Use in OAuth Flows These parameters can be used in any authorization request to an OAuth Authorization Server or OpenID Provider. Below are examples of including the new parameters in various OAuth flows and extensions.

OAuth Authorization Request

Pushed Authorization Requests (PAR) The parameters defined in are added to the Pushed Authorization Request as POST body parameters, as described in Section 2.1 of .

JWT-Secured Authorization Request (JAR) The parameters defined in are added to the Request Object as described in Section 4 of . The following is an example of the Claims in a Request Object before the base64url encoding and signing.

Security Considerations TODO

Client Authentication Because the parameters defined by this specification are not pre-registered at the Identity Provider, the Identity Provider is trusting the Authorization Server with the values provided in the request. For this reason, the Authorization Server MUST be a confidential client and use some form of client authentication to the Identity Provider.

Confidentiality The parameters defined by this specification may contain sensitive data, and should not be exposed to unnecessary parties. In particular, passing this data via the browser in redirects opens up opportunities for observing or tampering with this data. For this reason, Authorization Servers SHOULD use Pushed Authorization Requests and/or JWT-Secured Authorization Request to prevent tampering and exfiltration of the data.

Session Reference The session_ref parameter is meant to be a pointer to a session, and MUST NOT be the same value as the browser sends to the server as the session cookie.

Privacy Considerations TODO

IANA Considerations TODO

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] 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 The authorization request in OAuth 2.0 described in RFC 6749 utilizes query parameter serialization, which means that authorization request parameters are encoded in the URI of the request and sent through user agents such as web browsers. While it is easy to implement, it means that a) the communication through the user agents is not integrity protected and thus, the parameters can be tainted, b) the source of the communication is not authenticated, and c) the communication through the user agents can be monitored. Because of these weaknesses, several attacks to the protocol have now been put forward. This document introduces the ability to send request parameters in a JSON Web Token (JWT) instead, which allows the request to be signed with JSON Web Signature (JWS) and encrypted with JSON Web Encryption (JWE) so that the integrity, source authentication, and confidentiality properties of the authorization request are attained. The request can be sent by value or by reference. 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.

Document History (( To be removed from the final specification )) -00

• Initial Draft

Acknowledgments TODO