Configure token exchange¶

You can add a trusted token issuer to exchange tokens received from the configured third-party issuer for Asgardeo tokens.

Learn how to configure the OAuth 2.0 token exchange flow in your Asgardeo organization. Refer Token exchange grant for more information on how the flow works.

Follow this guide for instructions.

Register a trusted token issuer¶

To exchange a third-party token for an Asgardeo token, you need to register the third-party token issuer as a trusted token issuer in your Asgardeo organization.

To register a trusted token issuer:

On the Asgardeo 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 Asgardeo. The `aud` claim of the token should include the Asgardeo 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.
- 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.

Enable token exchange in your app¶

Before you begin

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

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

To enable token exchange in your application:

On the Asgardeo 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.

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¶

After enabling this configuration, 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:

On the Asgardeo 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 Asgardeo 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 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 to search for a matching local user account. If the system finds a matching account, Asgardeo 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.

Note

Asgardeo 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 Asgardeo 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 Asgardeo to perform the lookup.
Optionally, select a secondary attribute for Asgardeo 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 Asgardeo can't find a matching local user account using the primary lookup attribute, it searches for matching accounts using the secondary lookup attribute.

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.

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

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 '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

Asgardeo only copies the sub claim from the token received from the trusted token issuer to the exchanged Asgardeo token.

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