OAuth Token Exchange


The Token Exchange process is an extension on the OAuth 2.0 protocol, as described in the following draft specification: https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-19

It allows a Client to access multiple resources with a single access token, by exchanging it at IDHub for access tokens that have, for instance, a reduced scope.  It has the following two major use cases:

  • Impersonation
    A client is impersonating a principal, to gain access to its resources.  The impersonating client has all the rights of the principal it's impersonating.
  • Delegation
    A principal is acting as a delegate of another principal to access its resources.  It retains its own rights, and the resource is aware that this client is acting on behalf of a different client.  
    This mode is currently not supported by IDHub.

IDHub can accept access tokens, or SAML assertions from any known IDP, and exchange them for an access token to a specific resource (issued by IDHub). This can dramatically simplify the implementation on the side of the resource; as it only needs to integrate with a single IDP.  Which makes this a very useful implementation for a Microservices architecture, as an external access token can be exchanged for an internal token.

When to use Token Exchange?

There are scenarios when a Client accesses a resource server, which in turn needs to access resources hosted by other downstream services.

The Client sends in the access token that it received to IDHub, which acts as a Security Token Service (STS). IDHub will exchange the token provided by the Client with a token that can be used by the downstream service (Configured as an OAuth SP in IDHub).  This new token may have a reduced scope or expiration timestamp.

This setup is particularly useful in an architecture where lots of independent services exist, which each have their own OAuth Client ID. It allows all business and authorization logic to be concentrated in a single entity, and a single access token issuer can be used throughout the service landscape, greatly improving user experience.


The following flowchart explains the internal logic IDHub uses to validate a request under the Token Exchange grant.

  • Which IDP's are trusted? If the IDP is trusted, the token is validated based on the IDP's configuration (which must be set in IDHub)
  • Has the user given consent?
    If the downstream service accesses information of the user which requires content, IDHub will verify that this consent exists (for this combination of Scope, User and Service Provider).
    The token exchange will never request a user to grant consent, so the consent must already exist or be provided out of band.
  • Additional business logic via workflows

Using Token Exchange with a Workflow IDP

IDHub workflows (i.e. Internal IDP's) can be used as Identity Providers for a Token Exchange grant, as long as they provide a token which can be validated.

The IDP workflow also requires support for validating one of its own dispensed tokens. 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Please sign in to leave a comment.