Token Exchange
The token exchange grant type is used to exchange a token for another one. There are several use cases for this, where one can exchange one type of token for another one, or decrease/replace authorization of a token.
Token Exchange can happen in two forms: Impersonation or Delegation.
A client can impersonate another client by requesting a token exchange, and act as the client, and there is no trace of impersonation in the exchanged token.
A client can be delegated access from another client, by request a token exchange, and link a token to the exchanged token, thereby tracing that the token has been exchanged.
Only confidential clients are are eligible for token exchange, as it requires client authentication.
Only access_token and id_token can be used as subject, actor and requested tokens.
Only tokens from AuthServer are allowed to participate in token exchange.
The act claim is not nested, and does not allow for tracing a full transaction of multiple token exchanges.
Validation can be extended by implementing the interface "IExtendedTokenExchangeRequestValidator".
If the parameter "grant_type" is passed with value "urn:ietf:params:oauth:grant-type:token-exchange" to the token endpoint, then a subject_token is exchanged for a requested token.
The subject_token is used to exchange it for a new token, which is passed in the "access_token" field. The specific type of token is defined by the requestor, in the field "requested_token_type", and is also set in the response field "issued_token_type".
The following is an example HTTP request using token exchange.
POST /connect/token HTTP/1.1
Host: idp.authserver.dk
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=eyJhbGciOiJSUzI1NiIsImtpZCI...
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&requested_token_type=urn:ietf:params:oauth:token-type:access_token
&scope=account:update%20account:delete
&resource=https%3A%2F%2Fapi-one.protectedresource.dk
&resource=https%3A%2F%2Fapi-two.protectedresource.dk
The following is an example HTTP response using token exchange.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store
{
"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI...",
"expires_in": 300,
"scope": "account:update account:delete",
"token_type": "Bearer",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
If a protected resource receives a token with a lot privileges, and the protected resource needs to send it downstream, but less privilege is needed.
The protected resource can exchange the token with the least privilege required using token exchange.
If a protected resource receives a token that it needs to send downstream, but it is missing required privileges.
The protected resource can exchange the token with the required privilege required using token exchange.
If an end user needs to impersonate another end user, then audit and authorization can be needed. Token delegation can be used, to make sure the actor token is bound to the issued token. The request can be made more secure, by setting the "may_act" claim in the subject token, and its value is the subject claim of the actor token. This makes sure only the authorized end user can act on another users behalf.
Token exchange supports DPoP binding the issued token. The token is bound using the client requesting the token exchange.
Token exchange supports encrypting the issued token, if the requested type is id_token. The keys of the client requesting the token exchange, will be used to encrypt the token.