Chapter 7. Using token exchange

A successful response from an exchange invocation will return the HTTP 200 response code with a content type that depends on the requested-token-type and requested_issuer the client asks for. OAuth requested token types will return a JSON document as described in the OAuth Token Exchange specification.

{
   "access_token" : ".....",
   "refresh_token" : ".....",
   "expires_in" : "...."
 }

Clients requesting a refresh token will get back both an access and refresh token in the response. Clients requesting only access token type will only get an access token in the response. Expiration information may or may not be included for clients requesting an external issuer through the requested_issuer paramater.

Error responses generally fall under the 400 HTTP response code category, but other error status codes may be returned depending on the severity of the error. Error responses may include content depending on the requested_issuer. OAuth based exchanges may return a JSON document as follows:

{
   "error" : "...."
   "error_description" : "...."
}

Additional error claims may be returned depending on the exchange type. For example, OAuth Identity Providers may include an additional account-link-url claim if the user does not have a link to an identity provider. This link can be used for a client initiated link request.

The rest of this chapter discusses the setup requirements and provides examples for different exchange scenarios. For simplicity’s sake, let’s call a token minted by the current realm as an internal token and a token minted by an external realm or identity provider as an external token.

Clients that want to exchange tokens for a different client need to be authorized in the Admin Console. You need to define a token-exchange fine grain permission in the target client you want permission to exchange to.

Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange.

When your client is exchanging an existing token for a token targeting another client, you use the audience parameter. This parameter must be the client identifier for the target client that you configured in the Admin Console.

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:refresh_token" \
    -d "audience=target-client" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

The subject_token parameter must be an access token for the target realm. If your requested_token_type parameter is a refresh token type, then the response will contain both an access token, refresh token, and expiration. Here’s an example JSON response you get back from this call.

When the audience parameter is not set, the value of the parameter defaults to the client making the token exchange request.

Unlike with confidential clients, public clients are not allowed to perform token exchanges using tokens from other clients. If you are passing a subject_token, the (confidential) client that was issued the token should either match the client making the request or, if issued to a different client, the client making the request should be among the audiences set to the token.

If you are explicitly setting a target audience (with a client different from the client making the request), you should also make sure that the token-exchange scope permission is configured for the client set to the audience parameter to allow the client making the request to successfully complete the exchange.

{
   "access_token" : "....",
   "refresh_token" : "....",
   "expires_in" : 3600
}

Internal to external token exchange requests will be denied with a 403, Forbidden response until you grant permission for the calling client to exchange tokens with the external identity provider. To grant permission to the client, you go to the identity provider’s configuration page to the Permissions tab.

Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange.

When your client is exchanging an existing internal token to an external one, you provide the requested_issuer parameter. The parameter must be the alias of a configured identity provider.

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "requested_issuer=google" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

The subject_token parameter must be an access token for the target realm. The requested_token_type parameter must be urn:ietf:params:oauth:token-type:access_token or left blank. No other requested token type is supported at this time. Here’s an example successful JSON response you get back from this call.

{
   "access_token" : "....",
   "expires_in" : 3600
   "account-link-url" : "https://...."
}

If the external identity provider is not linked for whatever reason, you will get an HTTP 400 response code with this JSON document:

{
   "error" : "....",
   "error_description" : "..."
   "account-link-url" : "https://...."
}

The error claim will be either token_expired or not_linked. The account-link-url claim is provided so that the client can perform Client Initiated Account Linking. Most, if not all, providers require linking through browser OAuth protocol. With the account-link-url just add a redirect_uri query parameter to it and you can forward browsers to perform the link.

Before external token exchanges can be done, you grant permission for the calling client to make the exchange. This permission is granted in the same manner as internal to external permission is granted.

If you also provide an audience parameter whose value points to a different client other than the calling one, you must also grant the calling client permission to exchange to the target client specific in the audience parameter. How to do this is discussed earlier in this section.

The subject_token_type must either be urn:ietf:params:oauth:token-type:access_token or urn:ietf:params:oauth:token-type:jwt. If the type is urn:ietf:params:oauth:token-type:access_token you specify the subject_issuer parameter and it must be the alias of the configured identity provider. If the type is urn:ietf:params:oauth:token-type:jwt, the provider will be matched via the issuer claim within the JWT which must be the alias of the provider, or a registered issuer within the providers configuration.

For validation, if the token is an access token, the provider’s user info service will be invoked to validate the token. A successful call will mean that the access token is valid. If the subject token is a JWT and if the provider has signature validation enabled, that will be attempted, otherwise, it will default to also invoking on the user info service to validate the token.

By default, the internal token minted will use the calling client to determine what’s in the token using the protocol mappers defined for the calling client. Alternatively, you can specify a different target client using the audience parameter.

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    -d "subject_issuer=myOidcProvider" \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=target-client" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

If your requested_token_type parameter is a refresh token type, then the response will contain both an access token, refresh token, and expiration. Here’s an example JSON response you get back from this call.

{
   "access_token" : "....",
   "refresh_token" : "....",
   "expires_in" : 3600
}

The user that the subject token represents must have permission to impersonate other users. See the Server Administration Guide on how to enable this permission. It can be done through a role or through fine grain admin permissions.

Make the request as described in other chapters except additionally specify the requested_subject parameter. The value of this parameter must be a username or user id.

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=target-client" \
    -d "requested_subject=wburke" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

If the audience parameter is provided, then the calling client must have permission to exchange to the client. How to set this up is discussed earlier in this chapter.

Additionally, the calling client must be granted permission to impersonate users. In the Admin Console.

Your client now has permission to impersonate users. If you do not do this correctly, you will get a 403 Forbidden response if you try to make this type of exchange.

To make the request, simply specify the requested_subject parameter. This must be the username or user id of a valid user. You can also specify an audience parameter if you wish.

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "requested_subject=wburke" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token