Overview#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-05), defines a lightweight protocol extending OAuth 2.0 that enables clients to request and obtain security tokens from authorization servers acting in the role of an Security Token Service (STS).
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 STS protocol defined in this specification 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.
A new Grant Type for a 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 token-exchange 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.
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 client during token exchange 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.
Other OAuth 2.0 Token Exchange items to Note#
- JSON Web Token Claims
- Token Type Identifiers
- urn:ietf:params:oauth:token-type:access_token - indicate that the token is an OAuth 2.0 Access Token - same as "access_token" but as a URI
- urn:ietf:params:oauth:token-type:refresh_token - indicate that the token is an OAuth 2.0 Refresh Token - same as "refresh_token" but as a URI
- urn:ietf:params:oauth:grant-type:token-exchange - (new)
More Information#There might be more information for this subject on one of the following:
- Access Token
- Act (Actor) Claim
- Authentication Double-Hop
- Cid (Client Identifier) Claim
- JSON Web Token Claims
- May_act (May Act For) Claim
- Scp (Scopes) Claim
- Security Token Service
- [#1] - OAuth 2.0 Token Exchange: An STS for the REST of Us - based on information obtained 2016-01-05