Web Authorization Protocol I. Janicijevic Internet-Draft National Australia Bank Intended status: Standards Track 13 May 2024 Expires: 14 November 2024 OAuth 2.0 Delegated B2B Authorization draft-janicijevic-oauth-b2b-authorization-00 Abstract Delegated B2B Authorization enables a third-party OAuth client to obtain a limited access to an HTTP service on behalf of another OAuth client which is acting as a resource owner. This specification extends the OAuth 2.0 Authorization Framework with two new endpoints which allow a resource owner OAuth client to manage access for a third-party OAuth client. 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/. 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 14 November 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. Janicijevic Expires 14 November 2024 [Page 1] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 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 Terminology . . . . . . . . . . . . . . . . . 3 3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Client Registration . . . . . . . . . . . . . . . . . . . 5 3.2. Protocol Endpoints . . . . . . . . . . . . . . . . . . . 5 4. B2B Authorization Endpoint . . . . . . . . . . . . . . . . . 5 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Successful Response . . . . . . . . . . . . . . . . . . . 8 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . 9 5. Token Endpoint . . . . . . . . . . . . . . . . . . . . . . . 10 5.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.2. Successful Response . . . . . . . . . . . . . . . . . . . 10 5.3. Error Response . . . . . . . . . . . . . . . . . . . . . 11 6. B2B Authorization Revocation Endpoint . . . . . . . . . . . . 12 6.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 12 6.2. Successful Response . . . . . . . . . . . . . . . . . . . 13 6.3. Error Response . . . . . . . . . . . . . . . . . . . . . 13 7. Authorization Server Metadata . . . . . . . . . . . . . . . . 13 8. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 14 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 10.1. OAuth Authorization Server Metadata . . . . . . . . . . 14 10.2. OAuth Dynamic Client Registration Metadata . . . . . . . 15 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 11.1. Normative References . . . . . . . . . . . . . . . . . . 15 11.2. Informative References . . . . . . . . . . . . . . . . . 15 Appendix A. Document History . . . . . . . . . . . . . . . . . . 16 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 Janicijevic Expires 14 November 2024 [Page 2] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 1. Introduction The OAuth 2.0 Authorization Framework [RFC6749] enables a third- party OAuth client to obtain delegated access to an HTTP service on behalf of the end-user which is a resource owner. This use case is prevalent in consumer-to-business (C2B) interactions where resource owner is typically a person (human) and approval interaction between the parties is achieved via browser redirects. The [RFC6749] also allows the third-party OAuth client to obtain direct access to protected resources on its own behalf. This use case is prevalent in direct service-to-service (S2S) or business-to-business (B2B) interactions. In summary, [RFC6749] caters for delegated C2B access authorization and direct B2B access authorization; however, delegated B2B access authorization is not covered. There are business use cases where a third-party client needs to obtain access to protected resources held at resource provider on behalf of the resource owner client. These are the use cases where delegated B2B access authorization is required. This document defines two new OAuth 2.0 endpoints: the B2B authorization endpoint and the B2B authorization revocation endpoint, which allow a resource owner OAuth client to request and revoke access authorization for another (third-party) OAuth client. 2. Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying significance described in [RFC2119]. This specification uses the terms "token endpoint", "access token", "refresh token", "authorization server", "resource owner", "resource server", "authorization request", "authorization grant", "protected resource", "client", "confidential client", "client identifier", "client registration", and "client authentication" as defined by [RFC6749]. 3. Protocol Flow The following diagram depicts the overall architecture and the authorization protocol flow. Janicijevic Expires 14 November 2024 [Page 3] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 +------------+ +---------------+ | Resource |--(A)- Authorization Request ->| | | Owner | | | | |<-(B)-- Authorization Grant ---| | +------------+ | | | | | | | | (C) | | | | Authorization | Authorization | Server | Grant | | | | | | | | V | | +------------+ | | | |--(D)-- Authorization Grant -->| | | | | | | |<-(E)------ Access Token ------| | | | +---------------+ | Client | | | +---------------+ | |--(F)------ Access Token ----->| Resource | | | | Server | | |<-(G)--- Protected Resource ---| | +------------+ +---------------+ Figure 1: Abstract Protocol Flow The following steps describe this OAuth flow: (A) The resource owner client authenticates with the authorization server and requests authorization for the third party client. (B) The authorization server authenticates the resource owner client and issues an authorization grant, which is a credential representing the resource owner's authorization for the third party client and a grant id, which can be used to revoke the authorization grant, if required. (C) The resource owner client passes the authorization grant on to the third-party client. The way the resource owner client communicates with the third-party client is beyond the scope of this specification, however, the authorization grant MUST be passed to the third-party client in a secure manner. (D) The third-party client authenticates with the authorization server and requests an access token by presenting the authorization grant. Janicijevic Expires 14 November 2024 [Page 4] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 (E) The authorization server authenticates the third-party client and validates authorization grant, and if valid, issues an access token. (F) The third-party client requests the protected resource from the resource server and authenticates by presenting the access token. (G) The resource server validates the access token, and if valid, serves the request. 3.1. Client Registration Before initiating the protocol, both the resource owner client and the third-party client must be registered with the authorization server as confidential clients. The means through which the clients are registered with the authorization server are beyond the scope of this specification. 3.2. Protocol Endpoints The authorization process utilizes two authorization server endpoints, as follows: * B2B authorization endpoint - used by the resource owner client to obtain authorization for the third-party client. This is a new endpoint introduced by this specification. * Token endpoint - used by the third-party client to exchange the authorization grant for access token. This is the existing token endpoint as defined by [RFC6749]. The authorization grant management process utilizes one authorization server endpoint, as follows: * B2B authorization revocation endpoint - used by the resource owner client to revoke access for the third-party client. This is a new endpoint introduced by this specification. 4. B2B Authorization Endpoint This authorization server endpoint MUST use the "https" scheme and it MUST accept HTTP POST requests with parameters in the HTTP request message body using the "application/x-www-form-urlencoded" format as per Appendix B of [RFC6749] with UTF-8 character encoding. Janicijevic Expires 14 November 2024 [Page 5] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 This endpoint is used by the resource owner client to request the authorization grant for the third-party client. The authorization server MUST authenticate the resource owner client making requests to this endpoint by using the same rules as defined in [RFC6749] for token endpoint requests, and by using the registered authentication method indicated by the "token_endpoint_auth_method" client metadata parameter [RFC7591]. The authorization server indicates the client authentication methods supported when accepting requests to this endpoint by using the "token_endpoint_auth_methods_supported" authorization server metadata parameter [RFC8414]. 4.1. Request The resource owner client makes an HTTP POST request to this endpoint by sending the following parameters in the HTTP message body using the "application/x-www-form-urlencoded" format as per Appendix B of [RFC6749] with UTF-8 character encoding. client_id REQUIRED. The client identifier of the resource-owner client that is making the authorization request. request REQUIRED. The B2B authorization request object with authorization request parameters encoded as claims in a signed [RFC7515] and optionally encrypted [RFC7516] JSON Web Token (JWT) [RFC7519]. The B2B authorization request object includes the following claims: grant_details REQUIRED. JSON object with the following members: client_id REQUIRED. The client identifier of the third-party client that the authorization request is for. resource OPTIONAL. The resource(s) as defined in [RFC8707] that the third- party client SHOULD be authorized to access. If omitted, the third-party client SHOULD be authorized to access all resources that the owner client is authorized to access. A single "resource" parameter value is represented as a JSON string while multiple values are represented as an array of strings. Janicijevic Expires 14 November 2024 [Page 6] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 scope OPTIONAL. The scope(s) that the third-party client SHOULD be authorized to obtain. If omitted, the third-party client SHOULD be authorized to obtain all scopes which the resource owner client is authorized to obtain. expires_at OPTIONAL. The time when the authorization grant SHOULD expire. If omitted, the authorization grant SHOULD be valid until revoked by the resource owner client. The following is an example of claims in the B2B authorization object before base64url encoding and signing: { "iss": "s76gh32kjuolXaw", "aud": "https://server.example.com/as/b2b_authorize", "exp": 1715400380, "grant_details": { "client_id": "s56ghRwqo87bVxzs", "resource": "https://server.example.com/api/accounts", "scope": "accounts:read", "expires_at": 1731463200 } } For example, the resource owner client makes the following HTTP request using TLS (with extra line breaks for display purposes only): POST /as/b2b_authorize HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded client_assertion=eyJhbGciOiJSUzI1NiI ... sImtpZCI6IjIyIn0 &client_assertion_type= urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &client_id=s76gh32kjuolXaw &request=eyJhbGciOiJFUzI1NiIsImtpZCI6 ... IjE2In0 The authorization server MUST authenticate the resource owner client and validate the request object, including signature and expiry. The server then proceeds with validation of all the individual parameters included in the request object. Janicijevic Expires 14 November 2024 [Page 7] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 4.2. Successful Response The authorization server issues an authorization code and a grant identifier together with the details of the authorization granted. The authorization server constructs the response by adding the following parameters to the message body of the HTTP response with HTTP 200 OK status code by using "application/json" message format: response REQUIRED. The B2B authorization response object with authorization response parameters encoded as claims in a signed [RFC7515] and optionally encrypted [RFC7516] JSON Web Token (JWT) [RFC7519]. The B2B authorization response object includes the following claims: code REQUIRED. The authorization code generated by the authorization server. The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED. The third-party client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the third-party client identifier. grant_id REQUIRED. The authorization grant identifier that can be used by resource owner client to reference this authorization in the future. grant_details REQUIRED. JSON object with the following members: client_id REQUIRED. The client identifier of the third-party client that the authorization response is for. resource OPTIONAL. The resource(s) as defined in [RFC8707] that the third- party client is authorized to access. If omitted, the third-party client is authorized to access all resources that the owner client itself is authorized to access. A single "resource" parameter value is represented as a JSON string while multiple values are represented as an array of strings. Janicijevic Expires 14 November 2024 [Page 8] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 scope OPTIONAL. The scope(s) that the third-party client is authorized to obtain. If omitted, the third-party client will be authorized to obtain all scopes which the resource owner client itself is authorized to obtain. expires_at OPTIONAL. The time when the authorization grant will expire. If omitted, the authorization grant is valid until revoked by the resource owner client. An example successful response: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { response=eyJhbGciOiJFUtpZ ... CI6IjE2In0zI1NiIsIm } The following is an example of claims in the B2B authorization response object before base64url encoding and signing: { "code": "Ejr1zC2YoWpAAtnFZFsicM", "grant_id": "G5Qx2Tlzv3JKWIAtGOkF0X", "grant_details": { "client_id": "s56ghRwqo87bVxzs", "resource": "https://server.example.com/api/accounts", "scope": "accounts:read", "expires_at": 1731463200 } } 4.3. Error Response The authorization server returns an error response with the same format as is specified for error responses from the token endpoint in Section 5.2 of [RFC6749] using the appropriate error code from therein or from Section 4.1.2.1 of [RFC6749]. For example: Janicijevic Expires 14 November 2024 [Page 9] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "error": "invalid_request" } 5. Token Endpoint The token endpoint is used by the third-party client to obtain an access token and optionally a refresh token by presenting its authorization grant (authorization code). This end point is defined in section 3.2 of [RFC6749]. 5.1. Request The third-party client makes an access token request to this endpoint as specified in section 4.1.3 of [RFC6749]. 5.2. Successful Response The authorization server authenticates the third-party client and processes the access token request as specified in section 4.1.4 of [RFC6749]. In addition to the response parameters specified in [RFC6749], the authorization server adds the following parameters to the token endpoint response: grant_details REQUIRED. JSON object with the following members: client_id REQUIRED. The client identifier of the third-party client that the token response is for. resource OPTIONAL. The resource(s) as defined in [RFC8707] that the third- party client is authorized to access. If omitted, the third-party client is authorized to access all resources that the owner client itself is authorized to access. A single "resource" parameter value is represented as a JSON string while multiple values are represented as an array of strings. Janicijevic Expires 14 November 2024 [Page 10] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 scope OPTIONAL. The scope(s) that the third-party client is authorized to obtain. If omitted, the third-party client will be authorized to obtain all scopes which the resource owner client itself is authorized to obtain. expires_at OPTIONAL. The time when the authorization grant will expire. If omitted, the authorization grant is valid until revoked by the resource owner client. An example successful response: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", "grant_details": { "client_id": "s56ghRwqo87bVxzs", "resource": "https://server.example.com/api/accounts", "scope": "accounts:read", "expires_at": 1731463200 } } 5.3. Error Response The authorization server returns an error response with the same format as is specified for error responses from the token endpoint in Section 5.2 of [RFC6749] using the appropriate error code from therein or from Section 4.1.2.1 of [RFC6749]. For example: HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "error": "invalid_client" } Janicijevic Expires 14 November 2024 [Page 11] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 6. B2B Authorization Revocation Endpoint This authorization server endpoint MUST use the "https" scheme and it MUST accept HTTP POST requests with parameters in the HTTP request message body using the "application/x-www-form-urlencoded" format as per Appendix B of [RFC6749] with UTF-8 character encoding. This endpoint is used by the resource owner client to request the revocation of the previously issued authorization grant for the third-party client. The authorization server MUST authenticate the resource owner client making requests to this endpoint by using the same rules as defined in [RFC6749] for token endpoint requests, and by using the registered authentication method indicated by the token_endpoint_auth_method client metadata parameter [RFC7591]. The authorization server indicates the client authentication methods supported when accepting requests to this endpoint by using the "token_endpoint_auth_methods_supported" authorization server metadata parameter [RFC8414]. 6.1. Request The resource owner client makes an HTTP POST request to this endpoint by sending the following parameters in the HTTP message body using the "application/x-www-form-urlencoded" format as per Appendix B of [RFC6749] with UTF-8 character encoding. grant_id REQUIRED. The authorization grant identifier indicating the authorization grant that resource owner client want to revoke. For example, the resource owner client makes the following HTTP request using TLS (with extra line breaks for display purposes only): POST /as/b2b_revoke HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded client_assertion=eyJhbGciOiJSUzI1NiI ... sImtpZCI6IjIyIn0 &client_assertion_type= urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &grant_id=G5Qx2Tlzv3JKWIAtGOkF0X Janicijevic Expires 14 November 2024 [Page 12] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 6.2. Successful Response The authorization server MUST authenticate the resource owner client and validate the grant identifier. The server then proceeds with revocation of all tokens issued using this authorization grant and finally revokes the grant itself so that it cannot any longer be used to obtain access tokens. An example successful response: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store 6.3. Error Response The authorization server returns an error response with the same format as is specified for error responses from the token endpoint in Section 5.2 of [RFC6749] using the appropriate error code from therein or from Section 4.1.2.1 of [RFC6749]. For example: HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "error": "invalid_grant" } 7. Authorization Server Metadata The following authorization server metadata parameters [RFC8414] are introduced as part of this specification to signal the server's capability and policy with respect to the delegated B2B authorization. b2b_authorization_endpoint The URL at which a resource owner client can post an authorization request for the third-party client. b2b_authorization_revocation_endpoint The URL at which a resource owner client can post an authorization revocation request for the third-party client. Janicijevic Expires 14 November 2024 [Page 13] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 Note that the presence of the "b2b_authorization_endpoint" in the authorization server's metadata is sufficient for a resource owner client to determine that it may use the delegated B2B authorization flow. 8. Client Metadata The following client metadata parameter is introduced by this specification to indicate whether B2B authorization is supported by the resource owner client. b2b_authorization Boolean parameter indicating whether the resource owner client is registered for and supports delegated b2b authorization. If omitted, the default value is "false". 9. Security Considerations Resource owner client must be registered as confidential client because B2B authorization endpoint requires client authentication. Third-party client must be registered as confidential client because token endpoint requires client authentication. Authorization server must bind the authorization code to the third- party client id as specified in the authorization request. Resource owner must pass on the authorization code to the third-party client securely. Authorization server must not grant additional access (scopes and resources) to the third-party client from what was specified in the authorization request. Authorization server must not issue any tokens with validity greater than what was specified in the authorization request. If authorization grant is revoked by the resource owner the authorization server must revoke all related access tokens and refresh tokens issued to the third-party client. 10. IANA Considerations 10.1. OAuth Authorization Server Metadata IANA has registered the following values in the IANA "OAuth Authorization Server Metadata" registry of [IANA.OAuth.Parameters] established by [RFC8414]. Janicijevic Expires 14 November 2024 [Page 14] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 [[ TBA ]] 10.2. OAuth Dynamic Client Registration Metadata IANA has registered the following value in the IANA "OAuth Dynamic Client Registration Metadata" registry of [IANA.OAuth.Parameters] established by [RFC7591]. [[ TBA ]] 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, . 11.2. Informative References Janicijevic Expires 14 November 2024 [Page 15] Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, . Appendix A. Document History [[ To be removed from the final specification ]] Appendix B. Acknowledgments The author would like to thank Rupesh Santha Ramachandran, Mangesh Bopardikar and Naveen Tiku who contributed ideas and feedback that shaped and formed the final specification. This document was prepared using 2-Word-v2.0.template.dot. Author's Address Igor Janicijevic National Australia Bank Email: igor@ivagor.com Janicijevic Expires 14 November 2024 [Page 16]