OAuth 2.0 Delegated B2B Authorization

OAuth 2.0 Delegated B2B Authorization National Australia Bank

igor@ivagor.com

Web Authorization Protocol 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.

Introduction The OAuth 2.0 Authorization Framework 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 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, 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.

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

Protocol Flow The following diagram depicts the overall architecture and the authorization protocol flow.

Abstract Protocol Flow | | | 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 ---| | +------------+ +---------------+ ]]> 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.

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.

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 .

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.

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 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 for token endpoint requests, and by using the registered authentication method indicated by the "token_endpoint_auth_method" client metadata parameter . 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 .

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 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 and optionally encrypted JSON Web Token (JWT) .

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 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: For example, the resource owner client makes the following HTTP request using TLS (with extra line breaks for display purposes only): 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.

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 and optionally encrypted JSON Web Token (JWT) .

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 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: The following is an example of claims in the B2B authorization response object before base64url encoding and signing:

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 using the appropriate error code from therein or from Section 4.1.2.1 of . For example:

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 .

Request The third-party client makes an access token request to this endpoint as specified in section 4.1.3 of .

Successful Response The authorization server authenticates the third-party client and processes the access token request as specified in section 4.1.4 of . In addition to the response parameters specified in , 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 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:

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 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 for token endpoint requests, and by using the registered authentication method indicated by the token_endpoint_auth_method client metadata parameter . 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 .

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

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:

Authorization Server Metadata The following authorization server metadata parameters 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.

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

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.

IANA Considerations

OAuth Authorization Server Metadata IANA has registered the following values in the IANA "OAuth Authorization Server Metadata" registry of [IANA.OAuth.Parameters] established by .

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 .

References Normative References Key words for use in RFCs to Indicate Requirement Levels 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. The OAuth 2.0 Authorization Framework 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] OAuth 2.0 Authorization Server Metadata 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. Resource Indicators for OAuth 2.0 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. JSON Web Token (JWT) 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. JSON Web Signature (JWS) 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 Encryption (JWE) JSON Web Encryption (JWE) represents encrypted content 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 IANA registries defined by that specification. Related digital signature and Message Authentication Code (MAC) capabilities are described in the separate JSON Web Signature (JWS) specification. Informative References OAuth 2.0 Dynamic Client Registration Protocol 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.

Document History [[ To be removed from the final specification ]]

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.