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-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.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.
- 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.
- "act" (Actor) Claim
- "scp" (Scopes) Claim
- client_id Claim - carries the OAuth Client identifier of the OAuth 2.0 RFC 6749 client that requested the token.
- "may_act" (May Act For) Claim
More Information#There might be more information for this subject on one of the following:
- Access Token
- Act (Actor) Claim
- Authentication Double-Hop
- Delegation vs Impersonation
- JSON Web Token Claims
- May_act (May Act For) Claim
- OAuth 2.0 Token Exchange Request
- Scp (Scopes) Claim
- Security Token
- Security Token Service
- Token Type Identifiers
- [#1] - OAuth 2.0 Token Exchange: An STS for the REST of Us - based on information obtained 2016-01-05