OAuth2 - Token Exchange

OAuth 2.0 is a widely adopted framework for authorisation in web applications and APIs. While it provides essential grant types for obtaining tokens, the Token Exchange flow (defined in RFC 8693) is a powerful extension that addresses complex scenarios involving multiple services and token types. This flow enables the exchange of one type of token for another, making it particularly useful for cross-domain single sign-on (SSO), delegated access, token transformation, and confidential client access. For a comprehensive introduction to OAuth 2.0, you can refer to my OAuth 2.0 Introduction Article.

Why Use Token Exchange?

In short, token exchange allows a service to exchange a token from an Authority (Identity Provider) for a token from another Authority this is particularly useful in the the following situations:

• Cross-Domain Single Sign-On (SSO) : Different applications within a domain can exchange tokens to provide a seamless user experience without repeated login prompts.
• Delegated Access : A service acting on behalf of a user can exchange a user’s token for a token with specific permissions to access resources on another service.
• Token Transformation : Tokens can be transformed from one type to another, adapting to the requirements of different services or environments.
• Confidential Client Access : A confidential client (e.g., a backend service) can exchange a client credential for an access token, simplifying access management.

Steps involved in Token Exchange

1. Subject Token : The client initiates the flow by presenting a valid subject token. This could be an access token, refresh token, or even an assertion (like a SAML token).
2. Token Exchange Request : The client sends a request to the authorisation server’s token endpoint, including:
   • grant_type : set to urn:ietf:params:oauth:grant-type:token-exchange.
   • subject_token : The token to be exchanged.
   • subject_token_type : The type of the subject token (e.g. access_token, refresh_token).
   • audience (optional) : The intended recipient of the new token.
   • Additional parameters for specifying scopes or requested token type.
3. Token Exchange Response : If the request is valid and authorised, the authorisation server responds with:
   • access_token : The newly issued token.
   • token_type : Usually Bearer.
   • expires_in : Token lifetime.
   • Potentially other relevant metadata.

Delegation

The Token Exchange flow is specifically designed to facilitate delegation, which in essence means granting another entity the authority to act on behalf of yourself. This is done by granting a new token token with a scope that is specific to the delegated task to ensure the principal of least privilege, here is the process of delegation:

1. Subject Token : The subject (e.g., a user) obtains an initial access token that grants them permission to access certain resources.
2. Delegation Request : The actor (another service or application) requests to act on behalf of the subject. It presents the subject’s token to the authorisation server, along with its own actor token if applicable.
3. Token Exchange : The authorisation server validates both tokens and, if authorised, issues a new access token. This new token is scoped specifically for the actor’s intended actions on behalf of the subject.
4. Delegated Access : The actor can now use the new token to access the resources on behalf of the subject, within the constraints of the granted permissions.

The benefits of delegation are :

• Flexibility : It allows complex interactions between services and applications, enabling them to work together on behalf of users.
• Reduced Complexity : It simplifies user experience by avoiding the need for users to repeatedly authenticate with each service.
• Security : By using tokens with specific scopes and limited lifetimes, it helps to minimise the risk of unauthorised access.
• Auditing and Accountability : It allows for better tracking of which entity is performing actions on behalf of whom.

Scenario

Lets say that you manage a web application that has an Authority (Tenant) for all of your users and a second Authority (Tenant) for all internal or backend services. A user would not directly be able to communicate with a backend/internal service as their token would not be valid, this is where token exchange comes in.

• Client Authority : Issues tokens for all Users for the web application (e.g. an enterprise identity provider).
• Backend Authority : Protect all backend/internal resources (e.g. a cloud service provider).
• User : An authenticated user to the client website, wants to access data on a backend API.
• Client Website : A web application acting on behalf of the user wants to get data from the Backend API.

Explanation

1. Initial Token : The User has an access token issued by Client Authority, which she obtained through authentication (e.g., username/password).
2. Token Exchange: : The client application, acting on behalf of the User, sends the token from Client Authority to Backend Authority along with a token exchange request.
3. Trust Relationship : A trust relationship exists between Backend Authority and Client Authority. It validates the token, ensures the User is authorised, and issues a new token scoped to the resources the User can access.
4. Delegated Access : The client application can now use this new token from Backend Authority to access resources on behalf of the User.

Security Considerations

The Token Exchange flow introduces some important security aspects:

• Actor Token : In some cases, the client might present an actor token along with the subject token. This indicates the entity performing the exchange on behalf of the subject.
• Token Introspection : The authorisation server might need to introspect the subject token to verify its validity and scope.
• Trust Relationships : Securely implementing Token Exchange relies on established trust between the client, authorisation server, and the resource servers involved.
• Token Validation : Thoroughly validate all tokens involved in the flow to prevent unauthorised access or token misuse.
• Least Privilege : Follow the principle of least privilege, granting the actor only the minimum necessary permissions to perform its delegated tasks.
• Monitoring and Auditing : Regularly monitor and audit token exchange activity to detect any unusual or unauthorised behavior.

Scope Mapping between Authorities

As the Exchanged token will have different scopes than the original so that we can ensure that we keep to the principals of least privileged there needs to be a way to map scopes to permissions.

1. Direct Scope Mapping(Simplest) :
   • Predefined : Client Authority and Backend Authority establish a pre-agreed mapping between their scopes. For example:
     • openid (from client authority) maps to email profile (on Backend Authority)
     • read:calendar (from client authority) maps to calendar.events.read (on Backend Authority)
   • Configuration : This mapping is typically configured within Backend Authority, either directly in its settings or using a dedicated policy management tool.
   • Limitation : This works well for simple scenarios, but it can become unwieldy if there are many scopes or if the scopes change frequently.
2. Claims-Based Mapping (More Flexible) :
   • Token Introspection : Backend Authority introspects the token from Client Authority to obtain its claims (user information, permissions, etc.).
   • Rules Engine : Backend Authority uses a rules engine (or policy decision point) to evaluate these claims against its own authorisation policies. For example:
     • If the token has claim group:admin, grant scope write:documents
     • If the token has claim department:marketing, grant scope read:analytics
   • Advantages : This approach is more flexible, as it can handle complex authorisation logic and adapt to changes in the token claims or authorisation policies.
3. Token Transformation (Advanced) :
   • Scope Expansion/Reduction : Backend Authority can modify the scopes of the new token based on its policies and the original token’s claims. It can:
     • Expand : Grant additional scopes if certain conditions are met (e.g. add write:documents if the user is in a specific group).
     • Reduce : Remove scopes that are not relevant or allowed for the current context.
   • Claims Transformation : Backend Authority can also transform the claims within the new token to align with its own format or requirements.
   • Customisation : This level of control is ideal for complex scenarios where fine-grained authorisation is needed.

Additional Considerations

• Standardisation : There’s no strict standard for scope mapping, so authorities need to agree on their conventions and formats.
• Communication : If the mapping logic is complex, it might be beneficial for authorities to exchange metadata about their scopes and claims to facilitate interoperability.
• Security : Proper validation and mapping of scopes are essential to prevent unauthorised access or privilege escalation.

Conclusion

The OAuth 2.0 Token Exchange flow is a powerful mechanism that addresses the complex authorisation needs of modern distributed systems. It enables the secure exchange of tokens between different authorities, facilitating scenarios like cross-domain single sign-on, delegated access, and token transformation. By leveraging the principles of delegation and trust relationships, the Token Exchange flow streamlines user experiences, enhances security, and enables granular access control across diverse services.