Web Authorization Protocol A. Parecki Internet-Draft Okta Intended status: Standards Track 23 October 2023 Expires: 25 April 2024 OAuth Client and Device Metadata for Nested Flows draft-parecki-oauth-metadata-for-nested-flows-00 Abstract 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 This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://aaronpk.github.io/oauth-metadata-for-nested-flows/draft- parecki-oauth-metadata-for-nested-flows.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft- parecki-oauth-metadata-for-nested-flows/. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/. Source for this draft and an issue tracker can be found at https://github.com/aaronpk/oauth-metadata-for-nested-flows. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Parecki Expires 25 April 2024 [Page 1] Internet-Draft Metadata for Nested Flows October 2023 Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 25 April 2024. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 4 4. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 5 5. Use in OAuth Flows . . . . . . . . . . . . . . . . . . . . . 6 5.1. OAuth Authorization Request . . . . . . . . . . . . . . . 6 5.2. Pushed Authorization Requests (PAR) . . . . . . . . . . . 6 5.3. JWT-Secured Authorization Request (JAR) . . . . . . . . . 7 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 6.1. Client Authentication . . . . . . . . . . . . . . . . . . 8 6.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 8 6.3. Session Reference . . . . . . . . . . . . . . . . . . . . 8 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 9.2. Informative References . . . . . . . . . . . . . . . . . 9 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 Parecki Expires 25 April 2024 [Page 2] Internet-Draft Metadata for Nested Flows October 2023 1. 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. 2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2.1. 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 [RFC6749], and the terms "OpenID Provider" (OP) and "ID Token" defined by [OpenID]. TODO: Replace RFC6749 references with OAuth 2.1 This specification defines the following terms: Parecki Expires 25 April 2024 [Page 3] Internet-Draft Metadata for Nested Flows October 2023 "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. 3. 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 Section 4. 4. The User Agent visits the Identity Provider. 5. The Identity Provider authenticates the End-User. Parecki Expires 25 April 2024 [Page 4] Internet-Draft Metadata for Nested Flows October 2023 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 [RFC9126], JWT-Secured Authorization Request [RFC9101] 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 Section 5 for examples of how to provide the properties defined in this specification along with other OAuth extensions. 4. 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 Parecki Expires 25 April 2024 [Page 5] Internet-Draft Metadata for Nested Flows October 2023 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. 5. 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. 5.1. OAuth Authorization Request https://idp.example.com/authorize?response_type=code &state=af0ifjsldkj &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fas.example.org%2Fcb &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U &code_challenge_method=S256 &scope=openid+profile &application_class_id=1234 &application_class_name=Chat+for+iOS &device_id=9876 &device_name=Alice's+iPhone &session_ref=5124 5.2. Pushed Authorization Requests (PAR) The parameters defined in Section 4 are added to the Pushed Authorization Request as POST body parameters, as described in Section 2.1 of [RFC9126]. Parecki Expires 25 April 2024 [Page 6] Internet-Draft Metadata for Nested Flows October 2023 POST /par HTTP/1.1 Host: idp.example.com Content-Type: application/x-www-form-urlencoded response_type=code &state=af0ifjsldkj &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fas.example.org%2Fcb &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U &code_challenge_method=S256 &scope=openid+profile &application_class_id=1234 &application_class_name=Chat+for+iOS &device_id=9876 &device_name=Alice's+iPhone &session_ref=5124 5.3. JWT-Secured Authorization Request (JAR) The parameters defined in Section 4 are added to the Request Object as described in Section 4 of [RFC9101]. The following is an example of the Claims in a Request Object before the base64url encoding and signing. { "iss": "s6BhdRkqt3", "aud": "https://idp.example.com", "response_type": "code", "client_id": "s6BhdRkqt3", "redirect_uri": "https://as.example.org/cb", "scope": "openid profile", "state": "af0ifjsldkj", "max_age": 86400, "application_class_id": "1234", "application_class_name": "Chat for iOS", "device_id": "9876", "device_name": "Alice's iPhone", "session_ref": "5124" } 6. Security Considerations TODO Parecki Expires 25 April 2024 [Page 7] Internet-Draft Metadata for Nested Flows October 2023 6.1. 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. 6.2. 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 [RFC9126] and/or JWT-Secured Authorization Request [RFC9101] to prevent tampering and exfiltration of the data. 6.3. 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. 7. Privacy Considerations TODO 8. IANA Considerations TODO 9. References 9.1. Normative References [OpenID] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0", November 2014, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Parecki Expires 25 April 2024 [Page 8] Internet-Draft Metadata for Nested Flows October 2023 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 9.2. Informative References [RFC9101] Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021, . [RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, September 2021, . Appendix A. Document History (( To be removed from the final specification )) -00 * Initial Draft Acknowledgments TODO Author's Address Aaron Parecki Okta Email: aaron@parecki.com URI: https://aaronparecki.com Parecki Expires 25 April 2024 [Page 9]