On this page
A common use case is the need to exchange tokens issued by external or 3rd party IdP's for a token issued by the Curity Identity Server. There are several different scenarios that can drive this type of use case:
- A user authenticates with an external IdP and needs a Curity token to access a protected resource.
- An external service needs to access a Curity Identity Server-protected API on behalf of a user.
- An organization uses several different IdP's and wants to centralize access management.
This example Token Exchange Procedure:
- Accepts a JWT issued by an external IdP.
- Matches the audience (
audclaim) in the token with a list of approved audiences in the OAuth Client configured in the Curity Identity Server that has the OAuth 2.0 Token Exchange capability enabled. - Uses the configured Metadata URL to obtain the issuer and match with the
issclaim in the token. - Uses the Metadata URL to determine the JWKS endpoint and verifies the JWT.
- Performs downscoping as needed. Scopes issued in the token also has to be allowed on the configured OAuth Client or they will not be issued in the new token.
Installing the Plugin
You can build the plugin by issuing the command mvn package. This will produce a set of JAR files in the target/external-idp-token-exchange directory,
which can be installed.
To install the plugin, copy the compiled JAR files into a new directory in the plugins directory, e.g. ${IDSVR_HOME}/usr/share/plugins/external-idp-token-exchange
on each node, including the admin node. For more information about installing plugins, refer to the Curity Plugin SDK.
Configuration
The plugin only has a few settings to configure.
- Http Client - Create an HttpClient that the plugin will use to fetch the information from the configured Metadata URL.
- Metadata URL - This is the Metadata URL of the external IdP that has issued the JWT that is to be exchanged.
- Clock Skew - Configure as needed. The default is 2 seconds but can be adjusted accordingly.
Assign the plugin to the oauth-token endpoint
The Documentation describes in more detail how to assign the configured plugin to the Token OAuth Token Exchange flow on a oauth-token endpoint.
Also ensure that the client being used has the OAuth 2.0 Token Exchange capability enabled.
Using the Plugin
The plugin is used by sending a Token Exchange request to the oauth-token endpoint where the external IdP issued JWT is passed as the subject_token. An example request can look like:
curl -Ss -X POST \https://idsvr.example.com/oauth/v2/oauth-token \-H 'Content-Type: application/x-www-form-urlencoded' \-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \-d 'client_id=token-exchange-client' \-d 'client_secret=Pa$$w0rd!' \-d 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \-d 'scope=order_read inventory_write' \-d 'subject_token=eyJraW...ViCJ2hsMg6yslkaLsIgA' \
The expected response is a Curity Identity Server-issued JWT in the JSON response body:
{"token_type": "bearer","access_token": "eyJraWQiOiItMzMzMz...EoRORDFJXIiwgxvZA","issued_token_type": "urn:ietf:params:oauth:token-type:access_token","scope": "invoice_read","expires_in": 300}
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
