Token Exchange

Token exchange as recommended communication pattern between 2 apps on behalf of the user

The recommendation is to apply a token exchange as specified in RFC 8693.

The token exchange process issues a new token with a different audience, specified by the "aud" claim. This tells the receiving application that the token is intended (and allowed) for connecting to it. Therefore there must be a trust relation between the 2 clients at the authentication server in order to allow the token exchange process between them.

token exchange
The above image assumes that the API of AppB is called directly. However, APIs are often exposed on an API gateway - in particular Gravitee (see API Management Standardization). By subscribing to an API and the API owner approving this subscription a similar trust relation between both applications is created. The client configuration in PingFed can (usually) avoid that this trust relation needs to be specified in both places in this case (see section PingFed: How to).

Migration to full token exchange

Currently, access tokens are often passed from one application to another without being exchanged before. This is true for applications using both PingFed and Janus. Besides not considering the "aud" claim in the tokens (if that claim exists in the first place), this can cause an error when transitioning from one auth server (e.g. Janus) to the other (e.g. PingFed) as described in the below image. In such a case tokens from different clients are sent to the other auth server for token exchange but the exchange can only be performed for tokens of application A. Therefore the token exchange would fail for tokens originated from other client applications.

token exchange issue

If an application needs to perform a token exchange across different auth servers, then first all its upstream applications which send tokens to it need to implement the token exchange within the same auth server.

Since implementing and applying token exchange will only happen gradually in our landscape, there might be some workarounds needed until this is in place. These workarounds might include:

  • an application accepts tokens from both auth servers (i.e. in the above image appB would accept Janus and PingFed tokens).

  • instead of performing an actual token exchange across auth servers, the application creates a client token or a user token with a generic user from the other auth server and sends this token (i.e. in the above image appA creates such a token from Auth Server 2 and sends it to appB). However, this would only work if no authorization based on the end user is needed.