Internet-Draft OAuth 2.0 Delegated B2B Authorization May 2024
Janicijevic Expires 14 November 2024 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-janicijevic-oauth-b2b-authorization-00
Published:
Intended Status:
Standards Track
Expires:
Author:
I. Janicijevic
National Australia Bank

OAuth 2.0 Delegated B2B Authorization

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.

▲

Table of Contents

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.

+------------+                               +---------------+
|  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.

(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.

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.
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.

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.
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:

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.
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"
}

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

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.

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].

[[ 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, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.
[RFC8707]
Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, , <https://www.rfc-editor.org/info/rfc8707>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
[RFC7515]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, , <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516]
Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, , <https://www.rfc-editor.org/info/rfc7516>.

11.2. Informative References

[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, , <https://www.rfc-editor.org/info/rfc7591>.

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