Impersonation vs Delegation

Bob: a music enthusiast who has meticulously curated a collection of super cool playlists on an online music streaming platform

Alice: a close friend of Bob’s, who seeks access to his playlists to find the perfect soundtrack for her upcoming road trip

Alice is impersonating Bob

• The access credentials provided to the streaming platform don’t contain any information to recognize Alice’s identity.
• Whenever Alice accesses the platform, it believes Bob is the one using the service although the credentials used by Alice to access the service are different from Bob’s credentials.

The music streaming service has introduced features to support family and friend sharing. Alice can pass her identity information along with the temporary pass provided by Bob

• The access credentials to the streaming service contain information to recognize Alice’s identity in addition to Bob’s identity.
• When Alice accesses the service, it distinguishes between Bob and Alice, acknowledging Alice as Bob’s agent.

API Gateway Calls Backend API on Behalf of a Client

If you try to use the same token with the BE-API, it won’t work because the token isn’t intended for the BE-API and will be rejected by the BE-API after looking at the audience claim.

API-GW to request a new security token suitable for calling the backend API from the IdP by trading the current token sent by the client application.

The Token Exchange grant type facilitates this exchange, allowing the API-GW to request the audience and request scopes from the backend API.

In impersonation, the API-GW keeps its identity hidden from the backend API and acts as the end user accessing the API through the client application.

In delegation, the backend API recognizes that the API-GW is acting on behalf of the client application, which has obtained authorization from the end user.

The choice between these approaches depends on the specific design, business and security requirements of the system.

Microservice Calls Another Downstream Microservice

if you try to use the same token with the Order-Service, it won’t work because the token isn’t intended for the Order-Service and will be rejected by the Order-Service after looking at the audience claim.

Upgrading or downgrading the Scope of Security Tokens

The principle of elastic privilege

Applications should initially request a token with the minimal scopes required for current functionality, without making assumptions about future functionality that might require additional scopes.

Token Exchange becomes practical in such scenarios, allowing the application to obtain the required access token with required scopes when needed.

Application Accessing Resources in a Different Trust Domain

This is another use case perfectly suited for the Token Exchange grant type. However, compared to previous scenarios, this involves two trust domains and two IdPs, necessitating the existence of a trust relationship between these IdPs.

Workload Identity Federation

The Token Exchange grant type is very flexible, it lays out request and response messages, along with the message flow. However, it leaves certain crucial aspects open for implementation decisions, such as the supported token types and trust relationships, which are particularly important in cross-domain scenarios.

Request, response and the flow

The scenario where token exchange occurs within the same trust domain, facilitated by a single Identity Provider (IdP).

• This is an example where an API-GW that is generally recognized as a Resource Server (RS) within the OAuth2 terminology is designated as an OAuth2 client within the context of the Token Exchange. In the bottom line, depending on the circumstance, an entity different from a traditional OAuth2 client (e.g. — web and mobile apps) can participate in the Token Exchange by playing the client role.

As per the Token Exchange specification, the following parameters are mandatory in the request:

• grant_type: This parameter signals to the IdP that this is a token exchange request.
• subject_token: This parameter carries the current token received from the client, intended for exchange.
• subject_token_type: Denotes the type of the subject token (e.g., OAuth2 access token, OIDC IDToken, or SAML token).
• requested_token_type: (Optional) This parameter allows the client application to specify the desired token type. In the absence, the IdP may determine the token type based on the application’s configuration.

While not mandatory, parameters such as audience, resource, and scope are valuable for providing essential information about the target backend service to the IdP. This information helps the IdP identify the appropriate access policy for the target backend.

• resource: points to the location of the target, often represented as an HTTP URL.
• audience: reserved for the logical name associated with the target, a logical target name recognized by the Identity Provider (IdP).
• scope: you can include these scopes within the ‘scope’ request parameter.

In the impersonation use case demonstrated above, to employ Token Exchange in delegation, two additional parameters are required: actor_token and actor_token_type. These parameters provide identity information about the party requesting a new token.

• actor_token: The token that contains the information related to the identity of the token requesting party.
• actor_token_type: Denotes the type of the actor token.

The specification does not define any specific criteria for subject tokens to be considered valid for the token exchange. Nevertheless, it introduces the may_act claim, which an IdP could utilize to ascertain whether the requesting party is authorized to exchange their current subject token for a delegated token. This authorization can be verified by cross-referencing the may_act claim with either the requesting client’s identity or the identity information of the actor token.

there’s no standardized method for configuring and including may_act in the initial token destined to become the subject token in a subsequent stage.

The Token Exchange specification does not impose specific requirements for client registration or client authentication. However, in practical implementations, client authentication, often involving client secrets or other methods, is commonly employed to achieve the desired protection.

The Token Exchange response closely resembles standard OAuth2 responses but includes two additional parameters:

• issued_token_type: This parameter signifies the type of the issued token, aligning with parameters like requested_token_type, subject_token_type, and actor_token_type from the request.

• token_type: Unlike the previously mentioned parameters, this parameter informs the client how to use the access token to access the target resources. For example, a value of Bearer indicates that the issued security token can be presented as is, without additional proof of eligibility.

the access_token parameter in the response can be used to return various token types, not limited solely to access tokens. Here is a sample Token Exchange response message which returns an access token.

{
    "access_token": "eyJ4NXQiOiJOMk5tTUdGbE16UmtPV0l4WXpjNE9XTTNNekl5TURKaVpXVXdZMlF3T0dNeE5ERTVPV1JtWWpRd05EWXlOakkwTkRVM05UTmtZekl4TmpNNFl6RmxaQSIsImtpZCI6Ik4yTm1NR0ZsTXpSa09XSXhZemM0T1dNM016SXlNREppWldVd1kyUXdPR014TkRFNU9XUm1ZalF3TkRZeU5qSTBORFUzTlROa1l6SXhOak00WXpGbFpBX1JTMjU2IiwidHlwIjoiYXQrand0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIzM2Q5N2NjNS00M2M2LTQ0N2EtODE4Yi0xYWM4MDY2ZjU5ZDIiLCJhdXQiOiJBUFBMSUNBVElPTl9VU0VSIiwiYXVkIjoiXzM4Vm5YS0gyWTNyRDk5M21ZSEpNMWhWQzdVYSIsIm5iZiI6MTY5NTI2MzQ3NywiYXpwIjoiXzM4Vm5YS0gyWTNyRDk5M21ZSEpNMWhWQzdVYSIsIm9yZ19pZCI6Ijc0Y2MwZjJiLWUyMGYtNGQyNy1iYjQ1LTg2YjU0ODFhYWNiYyIsImlzcyI6Imh0dHBzOlwvXC9hcGkuYXNnYXJkZW8uaW9cL3RcL3NhZ2FyYW9yZ1wvb2F1dGgyXC90b2tlbiIsImV4cCI6MTY5NTI2NzA3Nywib3JnX25hbWUiOiJzYWdhcmFvcmciLCJpYXQiOjE2OTUyNjM0NzcsImp0aSI6ImM2ZmUyNDZhLWZkMDQtNDQ2Ni1hOGMwLTA4MzczYTMxNGY0MyIsImNsaWVudF9pZCI6Il8zOFZuWEtIMlkzckQ5OTNtWUhKTTFoVkM3VWEifQ.F6v5STHQVTvqsiYbVAbjgdeaj0QgMpkyVvxE5vd3aVUyGD3kNLw-C0ZaekNPDy6i--YKfhYljBKc3gqkO-YbZnpgAbZj7eCxOlNAp_JXqaAlU_sIP30PbCvXLBgLe5mwdJtMSI7NDSQ5nUo4TI_ZZp7HluTZ4nfvKJR1YKltp4D0eQLDCUfiIJHEwsafoAcANKfTbzEtg1vekChdstrakYP9na2xxGYAYZrdJgbUui2CnvfWpxwSRUqybJ_lM-CnrL-XSY70ppTB-y0RpcGtBAN0Usb1631-kbRXLDC8uZwN_pRjDywM5kjzvvrWkJWOuKKXzY1DDBJMEDWhWDWIPw",
    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "token_type": "Bearer",
    "expires_in": 3600
}

Let’s move into a cross-domain use case that we discussed above which involves two different IdPs.

• In this scenario, the Sales app initially acquires an access token from the Sales-IdP. This token allows access to the required API calls within the Sales-API.
• When the application needs to call the Loyalty-API to complete a business transaction, it creates a Token Exchange request. This request utilizes the current access token issued by the Sales-IdP.
• The Loyalty-IdP validates the received Token Exchange request. Notably, Loyalty-IdP recognizes the subject token’s origin, issued by the Sales-IdP, and proceeds to validate the token’s signature. While the specification does not prescribe a trust model or verification mechanism, a widely used approach is the JSON Web Key Set (JWKS), which contains public keys for signature verification. To establish trust, Loyalty-IdP should be configured with a JWKS URL from the Sales-IdP. However, it’s possible for an Idp to use different mechanisms to obtain the public keys of the other IdP involved such as directly uploading public keys.
• Upon successful verification, Loyalty-IdP issues a new access token, tailored to the correct audience and scope values required to access the Loyalty-API.
• The Sales app utilizes the newly received access token to seamlessly call the Loyalty-API and complete the intended business transaction.

The act claim

The act claim can be included in the introspection response of a delegated token, serving a consistent purpose throughout the token exchange process.

This structural flexibility is significant because it allows the act claim to capture a delegation chain by nesting act claims within one another. However, when making policy decisions, only the outermost act claim should be considered and the nested act claims are to provide information about the delegation chain.

How does OAuth Token Exchange work?

Token Exchange is a protocol where an existing token acts as the authorization grant for requesting a new token. This existing token, known as the subject token, serves as the foundation for the exchange.

While the specification does not require client authentication during a token exchange request, it is strongly recommended.

The token exchange protocol categorizes security tokens into three distinct types:

• Subject token: identifies the entity on whose behalf the client is requesting a new token. In most cases the subject remains unchanged. For example, when backend services use token exchange to reduce the scope of existing access tokens, any new access tokens still represent the same users.
• Actor token: an optional token, represents the entity attempting to act on behalf of the subject. While the newly issued token continues to reflect the same subject as the original subject token, it may also include a claim that identifies the actor, providing additional context about who is making the request.
• Requested token: is the token returned by the authorization server in response to a token exchange request. The authorization server issues the new token based on its policy, typically considering factors like the requested scope, token types, resources, and audiences.

Example of a Token Exchange Request:

POST /token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=eyJhbGciOiJIUzI1NiIsInR… (existing token)
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&requested_token_type=urn:ietf:params:oauth:token-type:refresh_token
&audience=https://api.target-service.com
&scope=read write

Example of a Token Exchange Response:

{
“access_token”: “new-access-token”,
“token_type”: “Bearer”,
“expires_in”: 3600,
“issued_token_type”: “urn:ietf:params:oauth:token-type:access_token”
}