Access tokens in the Microsoft identity platform

Access tokens enable clients to securely call protected web APIs. Web APIs use access tokens to perform authentication and authorization.

Per the OAuth specification, access tokens are opaque strings without a set format. Some identity providers (IDPs) use GUIDs and others use encrypted blobs. The format of the access token can depend on the configuration of the API that accepts it.

Custom APIs registered by developers on the Microsoft identity platform can choose from two different formats of JSON Web Tokens (JWTs) called v1.0 and v2.0. Microsoft-developed APIs like Microsoft Graph or APIs in Azure have other proprietary token formats. These proprietary formats that can't be validated might be encrypted tokens, JWTs, or special JWT-like.

The contents of the token are intended only for the API, which means that access tokens must be treated as opaque strings. For validation and debugging purposes only, developers can decode JWTs using a site like jwt.ms. Tokens that a Microsoft API receives might not always be a JWT that can be decoded.

Clients should use the token response data that's returned with the access token for details on what's inside it. When the client requests an access token, the Microsoft identity platform also returns some metadata about the access token for the consumption of the application. This information includes the expiry time of the access token and the scopes for which it's valid. This data allows the application to do intelligent caching of access tokens without having to parse the access token itself.

See the following sections to learn how an API can validate and use the claims inside an access token.

Note

All documentation on this page, except where noted, applies only to tokens issued for registered APIs. It doesn't apply to tokens issued for Microsoft-owned APIs, nor can those tokens be used to validate how the Microsoft identity platform issues tokens for a registered API.

There are two versions of access tokens available in the Microsoft identity platform: v1.0 and v2.0. These versions determine the claims that are in the token and make sure that a web API can control the contents of the token.

Web APIs have one of the following versions selected as a default during registration:

v1.0 for Azure AD-only applications. The following example shows a v1.0 token (the keys are changed and personal information is removed, which prevents token validation):

v2.0 for applications that support consumer accounts. The following example shows a v2.0 token (the keys are changed and personal information is removed, which prevents token validation):

Set the version for applications by providing the appropriate value to the accessTokenAcceptedVersion setting in the app manifest. The values of null and 1 result in v1.0 tokens, and the value of 2 results in v2.0 tokens.

An access token request involves two parties: the client, who requests the token, and the resource (Web API) that accepts the token. The resource that the token is intended for (its audience) is defined in the aud claim in a token. Clients use the token but shouldn't understand or attempt to parse it. Resources accept the token.

The Microsoft identity platform supports issuing any token version from any version endpoint. For example, when the value of accessTokenAcceptedVersion is 2, a client calling the v1.0 endpoint to get a token for that resource receives a v2.0 access token.

Resources always own their tokens using the aud claim and are the only applications that can change their token details.

The default lifetime of an access token is variable. When issued, the Microsoft identity platform assigns a random value ranging between 60-90 minutes (75 minutes on average) as the default lifetime of an access token. The variation improves service resilience by spreading access token demand over a time, which prevents hourly spikes in traffic to Azure AD.

Tenants that don't use Conditional Access have a default access token lifetime of two hours for clients such as Microsoft Teams and Microsoft 365.

Adjust the lifetime of an access token to control how often the client application expires the application session, and how often it requires the user to reauthenticate (either silently or interactively). To override the default access token lifetime variation, use Configurable token lifetime (CTL).

Apply default token lifetime variation to organizations that have Continuous Access Evaluation (CAE) enabled. Apply default token lifetime variation even if the organizations use CTL policies. The default token lifetime for long lived token lifetime ranges from 20 to 28 hours. When the access token expires, the client must use the refresh token to silently acquire a new refresh token and access token.

Organizations that use Conditional Access sign-in frequency (SIF) to enforce how frequently sign-ins occur can't override default access token lifetime variation. When organizations use SIF, the time between credential prompts for a client is the token lifetime that ranges from 60 - 90 minutes plus the sign-in frequency interval.

Here's an example of how default token lifetime variation works with sign-in frequency. Let's say an organization sets sign-in frequency to occur every hour. When the token has lifetime ranging from 60-90 minutes due to token lifetime variation, the actual sign-in interval occurs anywhere between 1 hour to 2.5 hours.

If a user with a token with a one hour lifetime performs an interactive sign-in at 59 minutes, there's no credential prompt because the sign-in is below the SIF threshold. If a new token has a lifetime of 90 minutes, the user wouldn't see a credential prompt for another hour and a half. During a silent renewal attempt, Azure AD requires a credential prompt because the total session length has exceeded the sign-in frequency setting of 1 hour. In this example, the time difference between credential prompts due to the SIF interval and token lifetime variation would be 2.5 hours.

Not all applications should validate tokens. Only in specific scenarios should applications validate a token:

If none of the above scenarios apply, there's no need to validate the token, and this may present a security and reliability risk when basing decisions on the validity of the token. Public clients like native, desktop or single-page applications don't benefit from validating ID tokens because the application communicates directly with the IDP where SSL protection ensures the ID tokens are valid. They shouldn't validate the access tokens, as these are for the web API to validate, not the client.

APIs and web applications must only validate tokens that have an aud claim that matches the application. Other resources may have custom token validation rules. For example, you can't validate tokens for Microsoft Graph according to these rules due to their proprietary format. Validating and accepting tokens meant for another resource is an example of the confused deputy problem.

If the application needs to validate an ID token or an access token, it should first validate the signature of the token and the issuer against the values in the OpenID discovery document.

The Azure AD middleware has built-in capabilities for validating access tokens, see samples to find one in the appropriate language. There are also several third-party open-source libraries available for JWT validation. For more information about Azure AD authentication libraries and code samples, see the authentication libraries. If you web app or web API is on ASP.NET or ASP.NET Core, use Microsoft.Identity.Web which handles the validation for you.

The examples below suppose that your application is validating a v2.0 access token (and therefore reference the v2.0 versions of the OIDC metadata documents and keys). Just remove the "/v2.0" in the URL if you validate v1.0 tokens.

A JWT contains three segments separated by the . character. The first segment is the header, the second is the body, and the third is the signature. Use the signature segment to evaluate the authenticity of the token.

Azure AD issues tokens signed using the industry standard asymmetric encryption algorithms, such as RS256. The header of the JWT contains information about the key and encryption method used to sign the token:

The alg claim indicates the algorithm used to sign the token, while the kid claim indicates the particular public key that was used to validate the token.

At any given point in time, Azure AD may sign an ID token using any one of a certain set of public-private key pairs. Azure AD rotates the possible set of keys on a periodic basis, so write the application to handle those key changes automatically. A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.

Acquire the signing key data necessary to validate the signature by using the OpenID Connect metadata document located at:

Tip

Try this in a browser: URL

The following information describes the metadata document:

Note

Use the kid claim to validate the token. Though v1.0 tokens contain both the x5t and kid claims, v2.0 tokens contain only the kid claim.

Doing signature validation is outside the scope of this document. There are many open-source libraries available for helping with signature validation if necessary. However, the Microsoft identity platform has one token signing extension to the standards, which are custom signing keys.

If the application has custom signing keys as a result of using the claims-mapping feature, append an appid query parameter that contains the application ID. For validation, use jwks_uri that points to the signing key information of the application. For example: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Web apps validating ID tokens, and web APIs validating access tokens need to validate the issuer of the token (iss claim) against:

OpenID Connect Core says "The Issuer Identifier [...] MUST exactly match the value of the iss (issuer) Claim." For applications that use a tenant-specific metadata endpoint (like https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration or https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), this is all that is needed.

This applies to applications which support:

Azure AD also supports multi-tenant applications. These applications support:

For these applications Azure AD exposes tenant-independent versions of the OIDC document at https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration and https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration respectively. These endpoints return an issuer value, which is a template parametrized by the tenantid: https://login.microsoftonline.com/{tenantid}/v2.0. Applications may use these tenant-independent endpoints to validate tokens from every tenant with the following modifications: instead of expecting the issuer claim in the token to exactly match the issuer value from metadata, the application should replace the {tenantid} value in the issuer metadata with the tenant ID that is the target of the current request, and then check the exact match (tid claim of the token).

In addition to the issuer of the token, applications using the v2.0 tenant-independant metadata need to validate the signing key issuer.

As discussed, from the OpenID Connect document, your application accesses the keys used to sign the tokens. It gets the corresponding keys document by accessing the URL exposed in the jwks_uri property of the OpenIdConnect document.

As above, {example-tenant-id} can be replaced by a GUID, a domain name, or common, organizations and consumers

The "keys" documents exposed by Azure AD v2.0 contains, for each key, the issuer that uses this signing key. See, for instance, the tenant-independent "common" key endpoint https://login.microsoftonline.com/common/discovery/v2.0/keys returns a document like:

The application should use the issuer property of the keys document, associated with the key used to sign the token, in order to restrict the scope of keys:

Using tenant-independent metadata is more efficient for applications that accept tokens from many tenants.

Note

With Azure AD tenant-independent metadata, claims should be interpreted within the tenant, just as under standard OpenID Connect, claims are interpreted within the issuer. That is, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} and {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} describe different users, even though the sub is the same, because claims like sub are interpreted within the context of the issuer/tenant.

Here is some pseudo code that recapitulates how to validate issuer and signing key issuer:

Refresh tokens are invalidated or revoked at any time, for different reasons. The reasons fall into the categories of timeouts and revocations.

Organizations can use token lifetime configuration to alter the lifetime of refresh tokens Some tokens can go without use. For example, the user doesn't open the application for three months and then the token expires. Applications can encounter scenarios where the login server rejects a refresh token due to its age.

The server possibly revokes refresh tokens due to a change in credentials, or due to use or administrative action. Refresh tokens are in the classes of confidential clients and public clients.

A non-password-based login is one where the user didn't type in a password to get it. Examples of non-password-based login include: