Configure token exchange

Token exchange is an OAuth 2.0 flow that allows the exchange of one type of token for another. Refer token exchange grant for more information on how this flow works.

This guide explains how you can set up token exchange flows in Asgardeo.

Register a trusted token issuer

When you register a third-party token issuer as a trusted token issuer in Asgardeo, a token received from it can be exchanged for an Asgardeo token.

To register a trusted token issuer in Asgardeo:

1. On the Asgardeo console, go to Connections.

2. Click Create Connection and click Create on Trusted Token Issuer.

3. 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	Issuer of the trusted token issuer. This is the value of the iss claim in the JWT generated from the external identity provider. Example: https://third-party-token-issuers.io/oauth2/token
   Alias	The name by which the trusted token issuer recognizes Asgardeo. If the aud claim of the token does not include the Asgardeo organization's issuer value, the value you assign here is validated against the aud claim.

4. Click Next and select a mode to obtain the certificate.

   A certificate is required to validate the signature of the assertions sent by the external identity provider. You can either provide a JWKS endpoint or upload a certificate.

   • JWKS endpoint: The JWKS endpoint of the trusted token issuer.
   • Provide certificates: Upload certificates of the token issuer in the .pem, .cer, .crt or .cert format.
     If you have a certificate in the .der format, convert it to the PEM format using OpenSSL

     Convert DER to PEM:

     openssl x509 -in cert.der -out cert.pem
     

5. Click Finish to add the new trusted token issuer.

Enable token exchange in your application

Before you begin

You need to register any one of the following application types with Asgardeo:

• Standard-based OIDC application
• Mobile application
• Traditional OIDC web application

Currently, Asgardeo does not support the token exchange grant type for single-page applications.

To enable token exchange in your application:

1. On the Asgardeo Console, go to Applications.

2. Open your application from the list and go to its Protocol tab.

3. Select Token Exchange under Allowed grant types.

   Additionally, select Refresh Token if you wish to enable refresh tokens for the token exchange grant. Learn more about refresh tokens.

4. Click Update to save the configurations.

Configure token exchange for a local user

Asgardeo can exchange a third-party 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

When this configuration is enabled, Asgardeo includes the local user profile information in the exchanged token if the federated identity has a linked local user account. Otherwise, Asgardeo returns the profile information received directly from the federated identity.

To prioritize linked local account attributes:

1. On the Asgardeo console, go to Applications.

2. Open your application from the list and go to its User Attributes tab.

3. Scroll down and under Linked Accounts, select Prioritize local account attributes.

   Select Mandate linked local account for Asgardeo to return an error if no user account linked to the federated identity is found.

Implicit account linking

You can use implicit account linking capability in the registered trusted token issuer to automatically create an account link between a local user account in Asgardeo and a federated identity during token exchange.

You can configure lookup attributes that will be used to search for a matching local user account. If an account is found, Asgardeo links the local user account automatically to the federated identity.

Once account links are established, administrators cannot delete them. Users can manage their own accounts links using the Manage linked accounts capability in the Self-service portal.

If prioritize local account attributes is disabled, Asgardeo will not perform implicit account linking even if the option is enabled.

To enable implicit account linking,

1. On the Asgardeo console, go to Connections.

2. Open the trusted token issuer you configured above and go to its Advanced tab.

3. Select Implicit account linking.

4. Select the primary attribute for Asgardeo to perform the lookup.

5. Optionally, select a secondary attribute for Asgardeo to perform the lookup.

   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 do not belong to them.

If a matching local user account could not be found using the primary lookup attribute, Asgardeo will use the secondary lookup attribute to search for matching local user accounts.
Following three attributes can be configured as lookup attributes

• http://wso2.org/claims/username

• http://wso2.org/claims/emailaddress

• http://wso2.org/claims/mobile

  Asgardeo will look for the mapped OpenID Connect attribute in the third-party token.

Try it out

Follow the steps given below to try out the token exchange flow.

1. Obtain a JWT from the third-party token issuer.

2. Execute the following cURL command to exchange the third-party token for an Asgardeo token.

   curl --location 'https://api.asgardeo.io/t/{organization_name}/oauth2/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'Authorization: Basic <base64 Encoded (clientId:clientSecret)>' \
   --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'
   

   If the issued Asgardeo token is not for a locally matched user account, Asgardeo copies over the sub claim received from the third-party token and includes as the sub in the issued token.

3. Upon successful execution, you will receive the exchanged token issued by Asgardeo.