OAuth 2.0 Token Exchange


OAuth 2.0 Token Exchange, an Internet Draft (OAuth 2.0 Token Exchange: An STS for the REST of Us /draft-ietf-oauth-token-exchange-09), defines a protocol for an HTTP- and JSON- based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 Authorization Servers, including Security Tokens employing impersonation and delegation.

Similar to OAuth 2.0, this specification focuses on client developer simplicity and requires only an HTTP client and JSON parser, which are nearly universally available in modern development environments. The Security Token Service protocol defined in OAuth 2.0 Token Exchange is not itself RESTful (an STS doesn't lend itself particularly well to a REST approach) but does utilize communication patterns and data formats that should be familiar to developers accustomed to working with RESTful systems.

OAuth 2.0 Token Exchange Request#

A new Grant Type for a urn:ietf:params:oauth:grant-type:token-exchange request and the associated specific parameters for such a request to the token_endpoint are defined by the OAuth 2.0 Token Exchange specification. A OAuth 2.0 Token Exchange Request response is a normal OAuth 2.0 response from the token_endpoint with a few additional parameters defined herein to provide information to the client.

NOT Restricted to OAuth Client#

The entity that makes the request to exchange tokens 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 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 AS 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 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 this specification.

OAuth 2.0 Token Exchange Response#

If the request is valid and meets all policy and other criteria of the Authorization Server, a successful token response is constructed by adding the following parameters to the entity-body of the HTTP Response using the "application/json" media type, as specified by RFC 7159, and an HTTP 200 status code. The parameters are serialized into a JavaScript Object Notation (JSON) structure by adding each parameter at the top level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.
  • access_token - REQUIRED - The security token issued by the authorization server in response to the token exchange request. The "access_token" parameter from Section 5.1 of RFC 6749 is used here to carry the requested token, which allows this token exchange protocol to use the existing OAuth 2.0 request and response constructs defined for the token endpoint. The identifier "access_token" is used for historical reasons and the issued token need not be an OAuth access token.
  • issued_token_type - REQUIRED - An Token Type Identifier, as described OAuth 2.0 Token Exchange in Section 3, for the representation of the issued security token.
  • token_type - REQUIRED - A case-insensitive value specifying the method of using the access token issued, as specified in Section 7.1 of RFC 6749. It provides the client with information about how to utilize the access token to access protected resources. For example, a value of "Bearer", as specified in RFC 6750, indicates that the security token is a bearer token and the client can simply present it as is without any additional proof of eligibility beyond the contents of the token itself. Note that the meaning of this parameter is different from the meaning of the "issued_token_type" parameter, which declares the representation of the issued security token; the term "token type" is typically used with this meaning, as it is in all "*_token_type" parameters in this specification. If the issued token is not an access token or usable as an access token, then the "token_type" value "N_A" is used to indicate that an OAuth 2.0 "token_type" identifier is not applicable in that context.
  • expires_in - RECOMMENDED - The validity lifetime, in seconds, of the token issued by the authorization server. Oftentimes the client will not have the inclination or capability to inspect the content of the token and this parameter provides a consistent and token type agnostic indication of how long the token can be expected to be valid. For example, the value 1800 denotes that the token will expire in thirty minutes from the time the response was generated.
  • scope - OPTIONAL - if the scope of the issued security token is identical to the scope requested by the client; otherwise, REQUIRED.
  • refresh_token - OPTIONAL - A refresh token will typically not be issued when the exchange is of one temporary credential (the subject_token) for a different temporary credential (the issued token) for use in some other context. A refresh token can be issued in cases where the client of the token exchange needs the ability to access a resource even when the original credential is no longer valid (e.g., user-not-present or offline scenarios where there is no longer any user entertaining an active session with the client). Profiles or deployments of this specification should clearly document the conditions under which a client should expect a refresh token in response to "urn:ietf:params:oauth:grant-type:token-exchange" grant type requests.

JSON Web Token Claims and Introspection Response Parameters#

The claims not established herein but used in examples and descriptions, such as "iss", "sub", "exp", etc., are defined by JWT.

More Information#

There might be more information for this subject on one of the following: