Token Exchange with a Trusted Identity Provider

SDL supports token exchange through the API gateway, allowing for secure token exchange with configured OpenID Connect (OIDC) identity providers.

Configuration

Token exchange is enabled when the API gateway is configured with the OIDC_TOKEN_EXCHANGE_IDP_LIST environment variable. This variable should contain the URLs of all configured OIDC identity providers in Keycloak.

If the value "default" is present in the OIDC_TOKEN_EXCHANGE_IDP_LIST, all identity providers will be ignored and no token exchange will be performed. This effectively disables the token exchange functionality.

How It Works

The API gateway acts as a token exchange broker, allowing clients to exchange tokens from trusted identity providers for SDL tokens. This enables:

Single sign-on (SSO) across different identity domains
Secure token exchange between trusted systems
Integration with external identity providers

Token Caching

By default, the API gateway caches exchanged tokens in Redis to improve performance and reduce the load on Keycloak. The caching behavior works as follows:

Tokens are cached using the external token’s JWT ID (jti) as the lookup key in Redis
The cache expiration time is set to match the external token’s expiration time — this ensures that cached tokens are automatically invalidated when the original token expires

Token caching can be disabled by setting the ENABLE_REDIS_CACHING environment variable to false in the API gateway configuration.

Configuring Token Exchange for an Identity Provider

To enable token exchange for an existing identity provider, follow these steps:

Navigate to the identity provider’s configuration in Keycloak
Select the "Permissions" tab
Enable permissions for the identity provider
From the permissions list, select the "token exchange" scope
On the token exchange configuration page, associate an appropriate policy with this permission

The policy you associate with the token exchange permission will determine which clients are allowed to exchange tokens with this identity provider. Choose a policy that aligns with your security requirements.

When configuring the token exchange permission, only modify the fields specified in these steps. Leave all other fields with their default values as populated by Keycloak.

Creating a Token Exchange Policy

If you need to create a new policy for token exchange:

When configuring the token exchange permission, click on the "policies" text box
Select the "create new policy" option
Choose "Client" as the policy type
Give the policy a meaningful name (e.g., "gateway-token-exchange")
In the clients list, select the client(s) that are configured for token exchange

When creating a new policy, only modify the fields specified in these steps. Leave all other fields with their default values as populated by Keycloak. For example, the "Logic" field should remain set to "positive".

Supported Identity Providers

The token exchange functionality supports any OIDC-compliant identity provider that is:

Configured in Keycloak
Listed in the OIDC_TOKEN_EXCHANGE_IDP_LIST environment variable
Properly configured for token exchange

Security Considerations

Only trusted identity providers should be added to the exchange list
Token exchange requests are validated for proper scope and audience
All exchanged tokens must meet SDL’s security requirements

Validating Token Exchange

You can validate that token exchange is working correctly by following these steps:

First, obtain a token from your trusted identity provider:

curl -k -X POST "$TRUSTED_PROVIDER_URL/auth/realms/$REALM/protocol/openid-connect/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=password" \
     -d "client_id=$IDP_CLIENT_ID" \
     -d "client_secret=$IDP_CLIENT_SECRET" \
     -d "username=$USERNAME_ON_IDP" \
     -d "password=$PASSWORD" \
     -d "scope=openid" | jq -r '.access_token'

Next, save the returned token to an environment variable:

export PROVIDER_TOKEN=<token_from_previous_step>

Finally, make a request to a protected endpoint that is behind the gateway:

curl -k -v -X GET https://map.$RDP_HOST/geoserver/rest/workspaces/nasa/coveragestores \
    -H "Authorization: Bearer $PROVIDER_TOKEN"

If token exchange is working correctly, the API gateway will:

Receive the request with the provider’s token
Exchange it for a SDL token
Forward the request to the backend service with the new token

The -k flag is used to skip SSL certificate validation. In production environments, you should use proper SSL certificates and remove this flag.

Testing Token Exchange Directly with Keycloak

To isolate and test the token exchange configuration in Keycloak (without involving the API gateway), you can use the following command:

curl -X POST \
        $RDP_HOST/auth/realms/data-fabric/protocol/openid-connect/token \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
        -d "subject_token=$IDP_TOKEN" \
        -d "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
        -d "client_id=$TOKEN_EXCHANGE_ENABLED_CLIENT" \
        -d "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
        -d "scope=openid"

This command tests the token exchange functionality directly at the Keycloak level, which can be useful for:

Verifying that the identity provider is properly configured for token exchange
Testing token exchange permissions and policies
Troubleshooting token exchange issues without the API gateway