Token exchange

RFC 8693 OAuth 2.0 Token Exchange

This resource issues tokens to registered Clients. A token exchange response is a normal OAuth 2.0 response from the token endpoint with a few additional parameters 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 resource to traditional OAuth clients. The issued token may be re-issued by the client to any other entity and used to access Key Bridge resources. For example, tokens could be assigned to a service resource consumer such as a radio access device, which can then authenticate itself to a spectrum access system.

Request and response

A client requests a security token by submitting a URL-encoded TokenExchangeRequest object to the token REST endpoint, as specified in RFC 8693 Section 2.1, where the grant_type parameter is set to urn:ietf:params:oauth:grant-type:token-exchange.

Client authentication follows standard password-based authentication per RFC 6749 Section 2.3.1, where the client_id and client_secret are the values issued during the automatic or portal registration process. See also RFC 2617.

On success, the authorization server responds with a complete TokenExchangeResponse object, as specified in RFC 8693 Section 2.2.

The following example represents a hypothetical token request in which an OAuth resource server assumes the role of the client during the exchange.

POST /token/oauth2 HTTP/1.1
Host: sts.example.com
Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
 &resource=https%3A%2F%2Fbackend.example.com%2Fapi
 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

The following is a non-normative example response, where the "access_token" parameter is the new token, which is itself a bearer OAuth access token.
In this example the token happens to be a JWT. For code tokens and opaque JWTs the "issued_token_type" would be set instead to urn:ietf:params:oauth:token-type:access_token.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo
   dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV
   4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn
   N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx
   f59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM
   y5-kdXjwhw",
 "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
 "token_type":"Bearer",
 "expires_in":60
}

Using the issued token

The client (or end-user entity) can immediately use the newly acquired access token to make an authenticated request to an access controlled resource server.

GET /access-controlled-api HTTP/1.1
Host: backend.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ
   iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2
   FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M
   zMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQe
   dw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIW
   vmDCMy5-kdXjwhw