RFC 8693 OAuth 2.0 Token Exchange

Introduction

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.

(This article is a partial reprint of the article "" on the .)

Specification

Token Types

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 of of IANA (Internet Assigned Numbers Authority).

  • JWT — urn:ietf:params:oauth:token-type:jwt
  • Access Token — urn:ietf:params:oauth:token-type:access_token
  • Refresh Token — urn:ietf:params:oauth:token-type:refresh_token
  • ID Token — urn:ietf:params:oauth:token-type:id_token
  • SAML 1.1 Assertion — urn:ietf:params:oauth:token-type:saml1
  • SAML 2.0 Assertion— urn:ietf:params:oauth:token-type:saml2

The token type identifier for JWT is defined in . Others are defined in .

Subject Token

A subject token “represents the identity of the party on behalf of whom the request is being made.” (excerpt from of )

The specification expects that the subject identified by the subject token is used as the subject of the newly issued token.

Actor Token

An actor token “represents the identity of the acting party.” (excerpt from of )

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. and of define JWT claims related to the acting party.

Token Exchange Request

A token exchange request is a kind of token requests.

Grant Type

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 specification does not require and even client identification at the token endpoint. of states it as follows.

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. ) and “unidentified clients” means that a token request does not contain information whereby to identify the client making the request.

Although of 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 by defining their own rules for secure token exchange.

Request Parameters

  • grant_type — REQUIRED. The value urn:ietf:params:oauth:grant-type:token-exchange indicates 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 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_token request parameter is given, this request parameter is REQUIRED. On the contrary, when the actor_token request parameter is not given, this request parameter must not be present.

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.

Response Parameters

  • 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 . In other cases, "N_A" is set.
  • 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. ).

Implementation

is supported by Authlete 2.3 onwards.

Regarding information about implementation, please refer to “” in the article “” on the .

Example

Authorization Server Implementation Example

in , an open-source sample implementation of authorization server written in Java, is a sample implementation of processing a token exchange request.

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.

ID_TOKEN=eyJraWQiOiJhdXRobGV0ZS1mYXBpZGV2LWFwaS0yMDE4MDUyNCIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL2ZhcGlkZXYtYXMuYXV0aGxldGUubmV0LyIsInN1YiI6IjEwMDQiLCJhdWQiOlsiNTg5OTQ2MzYxNDQ0ODA2MyJdLCJleHAiOjE2NTg2NzExMzAsImlhdCI6MTY1ODY3MDgzMCwiYXV0aF90aW1lIjoxNjU4NjcwODMwLCJub25jZSI6IjEyMzQ1Njc4OSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoibmlzdF84MDBfNjNBIn0sImNsYWltcyI6eyJnaXZlbl9uYW1lIjoiSW5nYSIsImZhbWlseV9uYW1lIjoiU2lsdmVyc3RvbmUiLCJiaXJ0aGRhdGUiOiIxOTkxLTExLTA2IiwiOmFnZV8xOF9vcl9vdmVyIjpudWxsfX19.mxE8FQaDb0edY_rWasSQ7pEMXbFon7oWr-Ccv1dB15q8eh2MaKRGrgvwPw_XjAdXlMNzkcV6iEUjRUvLGTvzm7_45cdoOxRX1xWzQw-vwvRbM46xd3Yht3EVjyRUUBJ_92J1yBmu7Nn93rygcnCE-fC_bSTSIJWgEnoC7dpxHYnoJ2QHrIOYFMBAA_3ZYCLGpgiWbIZnB2D1ib2eqwJ9zoJqeFNEBhXo9ThYkASHYaG-ZWofy7364lgeV4Rqy1r4XqzchFRW4yzWs_IM72bTtXTUkstlNOxZU12KEz50uVhtcOXv06iI71I9vceRP-ZVICpq7Knt0vEKWTM41E3ziw

(2) Make a token exchange request.

curl 
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange
-d subject_token=$ID_TOKEN
-d subject_token_type=urn:ietf:params:oauth:token-type:id_token
-d client_id=5908895171
-d scope=email

(3) Receive a token exchange response.

{
"access_token":"NEdL-q9EfOI4S5XzaMeimXAXVqS139Jm9DTYeLUAd5o",
"issued_token_type":
"urn:ietf:params:oauth:token-type:access_token",
"token_type":"Bearer",
"expires_in":86400,
"scope":"email",
"refresh_token":"pK9f5OWIrx58_XWrE_SpCLLN-BM673ljliTSffjqwao"
}

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Takahiko Kawasaki

Co-founder and representative director of Authlete, Inc., working as a software engineer since 1997.