Overview#
OAuth 2.0 Token Exchange Request (value "urn:ietf:params:oauth:grant-type:token-exchange") is an
Grant Type defined within the
OAuth 2.0 Token Exchange specification.
The
entity that makes a OAuth 2.0 Token Exchange Request is considered the client in the context of the
token exchange interaction. However, that does not restrict usage of this profile to traditional
OAuth Clients. An OAuth
Resource Server, for example, might assume the role of the
OAuth Client during
OAuth 2.0 Token Exchange Request request in order to trade an
Access Token, which it received in a
Protected Resource request, for a new token that is appropriate to include in a call to a backend service. The new token might be an access token that is more narrowly scoped for the downstream service or it could be an entirely different kind of
token.
The scope of the OAuth 2.0 Token Exchange Request specification is limited to the definition of a basic request and response protocol for an STS-style token exchange utilizing OAuth 2.0. Although a few new JWT claims are defined that enable delegation semantics to be expressed, the specific syntax, semantics and security characteristics of the tokens themselves (both those presented to the Authorization Server and those obtained by the client) are explicitly out of scope and no requirements are placed on the Trust Model in which an implementation might be deployed. Additional profiles may provide more detailed requirements around the specific nature of the parties and Trust Model involved, such as whether signing and/or encryption of tokens is required; however, such details will often be policy decisions made with respect to the specific needs of individual deployments and will be configured or implemented accordingly.
The security tokens obtained could be used in a number of contexts, the specifics of which are also beyond the scope of OAuth 2.0 Token Exchange.
2.1. Request#
A
OAuth Client requests a security
token by making a token request to the
Authorization Server's
token_endpoint using the extension grant type mechanism defined in Section 4.5 of OAuth 2.0
RFC 6749.
Client authentication to the Authorization Server is done using the normal mechanisms provided by OAuth 2.0. The supported methods of client authentication and whether or not to allow unauthenticated or unidentified clients are deployment decisions that are at the discretion of the Authorization Server.
The client makes a OAuth 2.0 Token Exchange Request Grant Type request to the token_endpoint with an extension grant type by including the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP Request entity-body:
- grant_type REQUIRED - The value "urn:ietf:params:oauth:grant-type:token-exchange" indicates that a token exchange is being performed.
- resource OPTIONAL - Indicates the physical location of the target service or resource where the client intends to use the requested security token. This enables the Authorization Server to apply policy as appropriate for the target, such as determining the type and content of the token to be issued or if and how the token is to be encrypted. In many cases, a client will not have knowledge of the logical organization of the systems with which it interacts and will only know the location of the service where it intends to use the token. The "resource" parameter allows the client to indicate to the Authorization Server where it intends to use the issued token by providing the location, typically as an https URL, in the token exchange request in the same form that will be used to access that resource. The authorization server will typically have the capability to map from a resource URI value to an appropriate policy. The value of the "resource" parameter MUST be an absolute URI, as specified by Section 4.3 of RFC 3986, which MAY include a query component and MUST NOT include a fragment component. Multiple "resource" parameters may be used to indicate that the issued token is intended to be used at the multiple resources listed.
- audience OPTIONAL - The logical name of the target service where the client intends to use the requested security token. This serves a purpose similar to the "resource" parameter, but with the client providing a logical name rather than a physical location. Interpretation of the name requires that the value be something that both the client and the authorization server understand. An OAuth Client client_id, a SAML entity identifier OASIS.saml-core-2.0-os, an OpenID Connect Issuer Identifier OpenID Connect Core 1.0, or a URI are examples of things that might be used as "audience" parameter values. Multiple "audience" parameters may be used to indicate that the issued token is intended to be used at the multiple audiences listed.
- scope OPTIONAL - a list of space-delimited, case-sensitive strings that allow the client to specify the desired scope of the requested security token in the context of the service or resource where the token will be used.
- requested_token_type OPTIONAL - an identifier, as described in Token Type Identifiers (OAuth 2.0 Token Exchange Section 3), for the type of the requested security token. For example, a JWT can be requested with the identifier "urn:ietf:params:oauth:token-type:jwt". If the requested type is unspecified, the issued token type is at the discretion of the Authorization Server and may be dictated by knowledge of the requirements of the service or resource indicated by the "resource" or "audience" parameter.
- subject_token REQUIRED - a security token that represents the identity of the party on behalf of whom the request is being made. Typically the subject of this token will be the subject of the security token issued in response to this request.
- subject_token_type REQUIRED - an identifier, as described in Token Type Identifiers (OAuth 2.0 Token Exchange Section 3), that indicates the type of the security token in the "subject_token" parameter. For example, a value of "urn:ietf:params:oauth:token-type:jwt", would indicate that the token is a JWT and a value of "urn:ietf:params:oauth:token-type:access_token" would indicate that the token is an OAuth Access Token.
- actor_token OPTIONAL - A security token that represents the identity of the party that is authorized to use the requested security token and act on behalf of the subject.
- actor_token_type - an identifier, as described in Token Type Identifiers (OAuth 2.0 Token Exchange Section 3), that indicates the type of the security token in the "actor_token" parameter. This is REQUIRED when the "actor_token" parameter is present in the request but MUST NOT be included otherwise.
- want_composite OPTIONAL - When the value of this parameter is "true", it indicates the client's desire for a composite security token to be issued, which contains claims about both the main subject of the token as well as about the party who is authorized to act on behalf of that subject. Note that this parameter only provides a means for the client to indicate its preference. The authorization server is not required to honor the stated preference and the nature of the tokens it issues are ultimately at its discretion.
There might be more information for this subject on one of the following: