Configure token exchange¶

You can exchange a token that an application already has for a new WSO2 Identity Server token. Learn how to configure the OAuth 2.0 token exchange flow in your WSO2 Identity Server organization. Refer to Token exchange grant for more information on how the flow works.

Follow this guide for instructions.

Enable token exchange in your app¶

Enable token exchange grant in the application that requests the new token.

Before you begin

You need to register any one of the following application types with WSO2 Identity Server:

Currently, WSO2 Identity Server does not support the token exchange grant for single-page applications.

To enable token exchange in your application:

On the WSO2 Identity Server Console, go to Applications.
Open your application from the list and go to the Protocol tab.
Add Token Exchange under the Allowed grant types.

Note

To enable refresh tokens for the token exchange grant, include Refresh Token as an Allowed Grant Type. Learn more about how the refresh token grant type works.
Click Update to save the configurations.

Note

To learn how token exchange can be invoked in organization applications, see Generate tokens for organization applications.

Token exchange flows¶

WSO2 Identity Server supports the following token exchange flows.

Federated token exchange: A third-party token issuer issues the subject token. You need to register that issuer as a trusted token issuer.
WSO2 Identity Server token exchange: WSO2 Identity Server issues the subject token.

Exchange a federated token¶

WSO2 Identity Server validates the subject token against the trusted token issuer you register for it, and issues a new token for the same identity.

Register a trusted token issuer

To exchange a federated token for a token issued by WSO2 Identity Server, you need to register the third-party token issuer as a trusted token issuer in your WSO2 Identity Server organization.

To register a trusted token issuer:

On the WSO2 Identity Server console, go to Connections.
Click New Connections and click Create on the Trusted Token Issuer.

Enter the following details of the trusted token issuer:

Parameter	Description
Trusted token issuer name	A unique name for the new trusted token issuer.
Issuer	A unique issuer value of the trusted token issuer. This is the value of the `iss` claim in the JWT token generated from the configured identity provider. Example: `https://third-party-token-issuers.io/oauth2/token`
Alias	The name by which the trusted token issuer knows WSO2 Identity Server. The `aud` claim of the token should include the WSO2 Identity Server organization's issuer value. If the `aud` claim doesn't include the organization's issuer value, the system validates the alias value you assign here against the `aud` claim.

Click Next and provide the mode of certificate configuration.
- JWKS endpoint: The JWKS endpoint of the trusted token issuer.
  Note
  
  For JWKS endpoints, the default read timeout equals 1000 milliseconds. To modify this value, add the following parameter to the deployment.toml file in the <PRODUCT_HOME>/conf/repository directory.
```
[oauth.jwks_endpoint]
read_timeout = <value in milliseconds>
```
- Use PEM certificate: Upload or paste the public certificate of the trusted token issuer. The certificate should be in PEM format.
  If you have a certificate in other formats such as .crt, .cer or .der, expand here to see how you can convert them to PEM format using OpenSSL
  Convert CRT to PEM
```
openssl x509 -in cert.crt -out cert.pem
```
  Convert CER to PEM:
```
openssl x509 -in cert.cer -out cert.pem
```
  Convert DER to PEM:
```
openssl x509 -in cert.der -out cert.pem
```
Click Finish to add the new trusted token issuer.

Configure token exchange for a local user

WSO2 Identity Server can exchange a federated token with a token issued for an existing local user account. This is beneficial if you wish to check for blocked/disabled user accounts or to enforce Role-Based Access Control (RBAC).

You can use the following properties to customize how token exchange occurs for identities with local user accounts.

Prioritize local account attributes

After enabling this configuration, WSO2 Identity Server includes the local user profile information in the exchanged token if the federated identity has a linked local user account. Otherwise, WSO2 Identity Server returns the profile information received directly from the federated identity.

To prioritize linked local account attributes:

On the WSO2 Identity Server console, go to Applications.
Open your application from the list and go to its User Attributes tab.
Scroll down and under Attribute Resolution for Linked Accounts, select Use linked local account attributes.

Note

Select Require linked local account for WSO2 Identity Server to return an error when it can't find a user account linked to the federated identity.

Implicit account linking

You can use implicit account linking in the registered trusted token issuer to create an account link automatically. The link connects a local user account in WSO2 Identity Server with a federated identity during token exchange.

You can configure lookup attributes to search for a matching local user account. If the system finds a matching account, WSO2 Identity Server automatically links the local user account to the federated identity.

After establishing account links, administrators can't delete them. Users can manage their own accounts links using the Manage linked accounts capability in the Self-service portal.

Important

When configuring implicit account linking, select lookup attributes (such as email, username, or externalId) that are unique across all user stores. This prevents failures when multiple accounts match the same attribute.

Note

WSO2 Identity Server skips implicit account linking when Require linked local account is disabled, even if the implicit linking option remains enabled.

To enable implicit account linking,

On the WSO2 Identity Server console, go to Connections.
Open the trusted token issuer you configured above and go to its Advanced tab.
Select Implicit account linking.
Select the primary attribute for WSO2 Identity Server to perform the lookup.
Optionally, select a secondary attribute for WSO2 Identity Server to perform the lookup.

Warning

Ensure that the chosen lookup attributes undergo verification by the third-party token issuer. If unverified, malicious users can manipulate attributes to gain access to local accounts that don't belong to them.

Note

If WSO2 Identity Server can't find a matching local user account using the primary lookup attribute, it searches for matching accounts using the secondary lookup attribute.

By default, the username attribute is available as a lookup attribute. Administrators can make an attribute unique across the user stores, after which it will appear in the lookup attributes list.

WSO2 Identity Server will look for the mapped OpenID Connect attribute in the federated token.

Try out federated token exchange

Follow the steps given below.

Get the JWT token received from the third-party token issuer.

Execute the following cURL command to exchange the federated token for an WSO2 Identity Server token.

curl --location 'https://localhost:9443/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <base64 Encoded (clientId:clientSecret)>' \
--data-urlencode 'scope=<desired scopes>' \
--data-urlencode 'subject_token=<jwt_token>' \
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
--data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange'

Note

WSO2 Identity Server only copies the sub claim from the token received from the trusted token issuer to the exchanged WSO2 Identity Server token.

Upon successful execution, you will receive the exchanged token.

Exchange a locally issued token¶

WSO2 Identity Server can also exchange a token that is issued by itself. This is beneficial if an application needs a token for a different application or a token with a narrower set of scopes.

Two applications take part in this flow.

Subject token application: The application that received the token needed to be exchanged.
Requesting application: The application that requests the new token. WSO2 Identity Server issues the exchanged token to this application.

The same application can play both roles.

Configure the subject token application

To configure the subject token application:

On the WSO2 Identity Server Console, go to Applications.
Open the subject token application from the list and go to the Protocol tab.
Under Access Token, select JWT as the Token type.
Click Update to save the configurations.

Try out locally issued token exchange

Follow the steps given below.

Get a JWT access token for the subject token application.

Execute the following cURL command to exchange the token for a new WSO2 Identity Server token.

curl --location 'https://localhost:9443/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <base64 Encoded (clientId:clientSecret)>' \
--data-urlencode 'scope=<desired scopes>' \
--data-urlencode 'subject_token=<jwt_token>' \
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
--data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange'

Upon successful execution, you will receive the exchanged token.

Delegation¶

The token exchange grant can also issue a token that preserves the identity of the party acting on behalf of the user. The requesting application presents an actor token along with the subject token, and WSO2 Identity Server records the acting party in the act claim of the exchanged token.

For instructions, see Delegation.

Request a specific audience¶

By default, WSO2 Identity Server adds all the audiences registered for the requesting application to the exchanged token. To limit the audience of the exchanged token to a single value, add the audience parameter to the token request with the required audience.

The requested audience should be one of the audiences registered for the requesting application. WSO2 Identity Server returns an invalid_target error if the request contains more than one audience value, or an audience that is not registered for the application.