RFC 8693 OAuth 2.0 Token Exchange is a technical specification that defines a way to get a new token by presenting an existing token and optionally one more existing token at the token endpoint. The mandatory input token is called “Subject Token” and the optional input token is called “Actor Token”.
The diagram below illustrates the token exchange flow.
The specification is very flexible. To put it the other way around, the specification does not define details that are necessary for secure token exchange. Therefore, authorization server implementations have to complement the specification with their own rules.
Thee tokens appear in the token exchange flow. They are a subject token, an actor token and a newly issued token. As possible types of the tokens, the specification lists the following token types and assigns token type identifiers to them. The identifiers of token types are registered at OAuth URI of OAuth Parameters of IANA (Internet Assigned Numbers Authority).
- JWT —
- Access Token —
- Refresh Token —
- ID Token —
- SAML 1.1 Assertion —
- SAML 2.0 Assertion—
The specification expects that the subject identified by the subject token is used as the subject of the newly issued token.
If there is a need to distinguish the subject of the newly issued token from the acting party that uses the token, authorization server implementations may utilize the actor token and embed information about the acting party in the token to issue. Section 4.1 and Section 4.4 of RFC 8693 define JWT claims related to the acting party.
Token Exchange Request
A token exchange request is a kind of token requests.
To distinguish token exchange requests from other token requests, a new grant type
urn:ietf:params:oauth:grant-type:token-exchange is defined in the specification. The value is used as the value of the
grant_type request parameter of a token request.
Client Identification and Authentication
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.
Technically speaking, “unauthenticated clients” means public clients (cf. RFC 6749 Section 2.1. Client Types) and “unidentified clients” means that a token request does not contain information whereby to identify the client making the request.
Although Appendix 1.1 of RFC 8693 shows an example of token exchange request from an unidentified client, it is risky to allow arbitrary unidentifiable clients (API callers) to make token exchange requests unconditionally. This is the reason that authorization server implementations have to complement RFC 8693 by defining their own rules for secure token exchange.
grant_type— REQUIRED. The value
urn:ietf:params:oauth:grant-type:token-exchangeindicates that the token request is a token exchange request.
resource— OPTIONAL. Resources to be tied to the newly issued token. This request parameter may be specified multiple times. See RFC 8707 Resource Indicators for OAuth 2.0 for details.
audience— OPTIONAL. Audience of the newly issued token. This request parameter also may be specified multiple times.
scope— OPTIONAL. A list of space-delimited names of scopes that are to be tied to the newly issued token.
requested_token_type— OPTIONAL. The token type of the newly issued token that the client wishes. One of the registered token type identifiers.
subject_token— REQUIRED. The value of the subject token.
subject_token_type— REQUIRED. The token type of the subject token. One of the registered token type identifiers.
actor_token— OPTIONAL. The value of the actor token.
actor_token_type— OPTIONAL. The token type of the actor token. One of the registered token type identifiers. When the
actor_tokenrequest parameter is given, this request parameter is REQUIRED. On the contrary, when the
actor_tokenrequest parameter is not given, this request parameter must not be present.
RFC 6749 The OAuth 2.0 Authorization Framework states “Request and response parameters MUST NOT be included more than once.” The
resource request parameter and
audience request parameter are exceptions.
Token Exchange Response
A token exchange response is a kind of token responses.
access_token— REQUIRED. Regardless of the token type, the value of the newly issued token is set to this response parameter.
issued_token_type— REQUIRED. The token type of the newly issued token. One of the registered token type identifier.
token_type— REQUIRED. When the token type of the newly issued token is
urn:ietf:params:oauth:token-type:access_token, this response parameter has the same meaning as defined in RFC 6749 The OAuth 2.0 Authorization Framework. In other cases,
expires_in— OPTIONAL. The lifetime of the newly issued token in seconds.
scope— OPTIONAL. Scopes tied to the newly issued token. When the actual set of scopes tied to the newly issued token is different from the set requested by the token exchange request, this response parameter is REQUIRED.
refresh_token— OPTIONAL. A refresh token (cf. RFC 6749 Section 6. Refreshing an Access Token).
RFC 8693 is supported by Authlete 2.3 onwards.
Authorization Server Implementation Example
Note that the implementation is just an example and does not intend to be perfect for commercial use.
Request and Response Example
(1) Prepare an ID Token in some way or other.
(2) Make a token exchange request.
(3) Receive a token exchange response.