Token-exchange is an Grant Type
defined within the OAuth 2.0 Token Exchange
A client requests a security token by making a token request to the Authorization Server
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. Section 2.3.1 of The OAuth 2.0 Authorization Framework RFC 6749 defines password-based authentication of the client, however, client authentication is extensible and other mechanisms are possible. For example, RFC 7523 defines client authentication using JSON Web Tokens (JWTs) JWT. 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 Token-exchange 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:
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.
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.
An identifier, as described in 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.
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.
An identifier, as described in 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
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.
An identifier, as described in 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.
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: