Azure AD Token Exchange Best Practices and Concepts

Azure AD Token Exchange is a powerful feature that enables seamless authentication and authorization across different applications and services. It's a crucial component of Azure Active Directory (Azure AD) that simplifies the process of obtaining and managing access tokens.

The token exchange process involves converting an existing token into a new one that's valid for a different audience or application. This is achieved through the use of token exchange policies, which are configured in Azure AD.

Token exchange policies can be applied to different scenarios, such as exchanging a token for a user's identity or exchanging a token for a group's identity. This flexibility makes Azure AD Token Exchange a versatile tool for managing authentication and authorization.

By following best practices and understanding the underlying concepts, you can effectively implement Azure AD Token Exchange in your organization and enjoy the benefits of simplified authentication and authorization.

Traditional OAuth Flows involve a client application requesting access to protected resources using an access token issued by Verify. This application is registered on Verify and requests tokens only from Verify.

The user or API client authenticates with or through Verify. This is the typical flow, but it's not the only way to get an access token.

In a traditional OAuth flow, the client application requests access to protected resources using an access token issued by Verify. This application is registered on Verify and requests tokens only from Verify.

Here are the different types of tokens that can be validated by Verify:

These tokens can be validated in different ways, depending on the type of token and the configuration of Verify. For example, a token issued by the same Verify tenant is introspected for validity.

Azure AD Token Exchange is a powerful feature that allows you to exchange identity tokens for access tokens, enabling your applications to access protected resources. This process involves several key components, including the subject token, subject token type, and requested token type.

To initiate a token exchange, you'll need to configure your TrustframeworkExtensions.xml file to include the necessary claim types and output claims. Specifically, you'll need to add a ClaimType element for the identity provider access token and an OutputClaim element to the TechnicalProfile element for each OAuth 2.0 identity provider.

Here are some common use cases for token exchange:

Note that the specifics of token exchange can vary depending on the use case and the identity provider being used. Be sure to consult the relevant documentation for more information.

The Authorization Code flow is a common way to get tokens in Azure AD, and it's similar to the normal auth code flow, but with an additional code_verifier parameter.

You'll need to make a POST request to the token endpoint, which is in the format https://{{tenant}}.b2clogin.com/{{tenant}}.onmicrosoft.com/{{policy}}/oauth2/token.

The request should have the following parameters: grant_type=authorization_code, code={{code}}, client_id={{clientId}}, code_verifier={{codeVerifier}}, and redirect_uri=https://jwt.ms.

If the call is successful, it will return a JSON object with an access_token, id_token, and refresh_token.

The refresh_token property is what you'll mostly be interested in, as it can be used to get a new access token without the user needing to reauthenticate.

Note that the refresh token has a shorter lifetime than traditional refresh tokens, and it's not necessary to specify the offline_access scope in the request.

Also, keep in mind that the refresh_token_expires_in property is outside the OAuth standard, so you'll need to check if the refresh token is valid by trying to use it.

Impersonation is a common usage of token exchange, where a service acts on behalf of the subject of a token to access a protected resource.

In Azure AD Token Exchange, impersonation allows a service to exchange a client app token for a new token that has permissions to access a different resource. This is useful when the original token lacks permissions to directly access the resource.

For example, a client app may be issued a token to access a protected resource, but that token may not have the necessary permissions to access another resource. In this case, the service can impersonate the client app and request a new token with the required permissions.

Impersonation enables services to perform actions on behalf of the subject of the token, making it a powerful tool in Azure AD Token Exchange.

Delegation in Azure AD Token Exchange allows a user to act on behalf of another user, which is a common scenario in relationship-based authorization. This is achieved by including an actor token as a parameter, along with a corresponding actor token type, to validate the actor.

In a medical clinic, for example, any doctor can access patient information, so the actor token that represents a doctor may be a JWT with a specific payload. The subject token, which identifies the patient, includes a may_act claim that indicates which actors can request a new patient token.

The may_act claim can have multiple properties, and all of them must match the properties in the actor token. This ensures that only authorized actors can access the patient's information. Verify offers the ability to evaluate an access policy as part of the token exchange flow to perform finer-grained authorization checks.

Here are the key components of delegation in Azure AD Token Exchange:

By using delegation in Azure AD Token Exchange, you can ensure that only authorized actors can access sensitive information, and that the right permissions are in place to prevent unauthorized access.

Refresh IDP is a crucial aspect of Azure AD Token Exchange, allowing you to exchange an external identity provider's token for an access token that can be used to access protected resources.

To pass the identity provider's refresh token, you'll need to add a ClaimType element to your TrustframeworkExtensions.xml file with an identifier of identityProviderRefreshToken.

Some identity providers, like Facebook, Google, and GitHub, issue a refresh token that can be used to obtain a new access token when needed.

You can add the OutputClaim element to the TechnicalProfile element for each OAuth 2.0 identity provider that you'd like the refresh token for, as shown in the example for Facebook.

To do this, you'll need to include metadata or scopes in the identity provider's technical profile, depending on the provider's requirements.

Here's a summary of the steps to pass the identity provider's refresh token:

An access token is a short-lived token that contains sensitive information, and it's used to access Azure APIs. It's typically short-lived, and is retrieved by proving your identity and specifying what resource(s) you want to access and how.

There are three types of tokens in Azure: Access Tokens, Refresh Tokens, and Id Tokens. Access Tokens are used to access Azure APIs, Refresh Tokens are used to get a new Access Token when the current one expires, and Id Tokens contain information about the user or identity that the token belongs to.

To use an access token, you need to acquire it first. You can do this by using the Device Code flow, which is designed for situations where you can't browse to a URL. This flow involves displaying a user code and URL, and then polling the token endpoint to see if the user has logged in yet.

Here are the parameters you need to implement for the Device Code flow:

By using these parameters, you can implement the Device Code flow and get an access token to access Azure APIs.

When you're dealing with an external identity provider, things can get a bit more complicated. Azure AD token exchange comes to the rescue in such scenarios.

The client application needs to access a protected resource API, but the user authenticates through an external identity provider. In this case, the app is issued an identity token in the form of a signed JWT as part of user authentication.

To access the protected resources, the app has to exchange the identity token for an appropriate access token. This is where OAuth 2.0 Token Exchange helps.

Here's a breakdown of the process:

In the case of Verify, the subject token is the Verify issued access token that can be validated natively. The subject token type is the native access token type supported by Verify. The requested token type is also the native access token type supported by Verify.

OAuth 2.0 is the industry-standard protocol used for modern authorization in various services.

It's worth noting that OAuth 2.0 is designed around different client profiles, and we can think of a client as anything from a PowerShell script to a mobile app or serverless application.

The protocol is used in Azure APIs, and there are extensions like OpenID Connect that implement authentication in addition to authorization.

Microsoft uses OpenID Connect to enable Single Sign-On (SSO) between services and secret-free deployments in Azure DevOps.

OAuth 2.0 is designed to handle different client profiles, including a PowerShell script running on a server or in an interactive session.

There are several defined parties involved in the flows, but we'll simplify the visuals by only showing the client.

Token grant types, or flows, are the patterns in OAuth 2.0 for requesting tokens, and they're essential for retrieving tokens.

These flows can be very different depending on the client, such as a timer-triggered Azure Function running in the cloud versus a user in an interactive PowerShell session.

There are several defined token grant types, and they're bundled together under the same flows, but we'll define them separately.

OAuth 2.0 is designed around these client profiles, and we can think of a client as anything from a PowerShell script to a mobile app or serverless application.

The client is a crucial party in the flows, and we can also technically open a HTTP listener on a port to pick up the authorization code from the response query parameters.

AzAuth is a better tool to use in this scenario, though.

PKCE is a security extension to the Authorization Code flow, recommended to use wherever possible because it increases security. It adds two more parameters to the auth code exchange.

PKCE works in a similar way to verifying cryptographic signatures, like certificates. We define a string called the code_verifier, which should be long and complex, but for a simpler example, let's take the string secret123.

The code_verifier is hashed with SHA256 to create a secret string called code_challenge, which is sent to the Azure AD as the Authorization Server in the flow.

Azure AD will bake the code_challenge into the auth code response, which we use in the request for the access token. The code_verifier is also sent to Azure AD, alongside the auth code.

Before Azure AD gives us an access token back, it verifies that using SHA256 on the code_verifier becomes the same hashed code_challenge string, proving that no one modified anything along the way since it would have broken the auth code.

Here are the two additional parameters added by PKCE:

PKCE is a clever solution that takes the state parameter to the next level by adding these two more parameters to the auth code exchange.