Azure AD token reference

Azure Active Directory (Azure AD) emits several types of security tokens in the processing of each authentication flow. This document describes the format, security characteristics, and contents of each type of token.

Types of tokens

Azure AD supports the OAuth 2.0 authorization protocol, which makes use of both access_tokens and refresh_tokens. It also supports authentication and sign-in via OpenID Connect, which introduces a third type of token, the id_token. Each of these tokens is represented as a "bearer token".

A bearer token is a lightweight security token that grants the “bearer” access to a protected resource. In this sense, the “bearer” is any party that can present the token. Though authentication with Azure AD is required in order to receive a bearer token, steps must be taken to secure the token, to prevent interception by an unintended party. Because bearer tokens do not have a built-in mechanism to prevent unauthorized parties from using them, they must be transported in a secure channel such as transport layer security (HTTPS). If a bearer token is transmitted in the clear, a man-in the middle attack can be used to acquire the token and gain unauthorized access to a protected resource. The same security principles apply when storing or caching bearer tokens for later use. Always ensure that your app transmits and stores bearer tokens in a secure manner. For more security considerations on bearer tokens, see RFC 6750 Section 5.

Many of the tokens issued by Azure AD are implemented as JSON Web Tokens, or JWTs. A JWT is a compact, URL-safe means of transferring information between two parties. The information contained in JWTs are known as "claims", or assertions of information about the bearer and subject of the token. The claims in JWTs are JSON objects encoded and serialized for transmission. Since the JWTs issued by Azure AD are signed, but not encrypted, you can easily inspect the contents of a JWT for debugging purposes. There are several tools available for doing so, such as For more information on JWTs, you can refer to the JWT specification.


Id_tokens are a form of sign-in security token that your app receives when performing authentication using OpenID Connect. They are represented as JWTs, and contain claims that you can use for signing the user into your app. You can use the claims in an id_token as you see fit - commonly they are used for displaying account information or making access control decisions in an app.

Id_tokens are signed, but not encrypted at this time. When your app receives an id_token, it must validate the signature to prove the token's authenticity and validate a few claims in the token to prove its validity. The claims validated by an app vary depending on scenario requirements, but there are some common claim validations that your app must perform in every scenario.

See the following section for information on id_tokens claims, as well as a sample id_token. Note that the claims in id_tokens are not returned in any particular order. In addition, new claims can be introduced into id_tokens at any point in time - your app should not break as new claims are introduced. The following list includes the claims that your app can reliably interpret at the time of this writing. If necessary, even more detail can be found in the OpenID Connect specification.

Sample id_token



For practice, try inspecting the claims in the sample id_token by pasting it into

Claims in id_tokens

JWT Claim Name Description
appid Application ID Identifies the application that is using the token to access a resource. The application can act as itself or on behalf of a user. The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.

Example JWT Value:
aud Audience The intended recipient of the token. The application that receives the token must verify that the audience value is correct and reject any tokens intended for a different audience.

Example SAML Value:

Example JWT Value:
appidacr Application Authentication Context Class Reference Indicates how the client was authenticated. For a public client, the value is 0. If client ID and client secret are used, the value is 1.

Example JWT Value:
"appidacr": "0"
acr Authentication Context Class Reference Indicates how the subject was authenticated, as opposed to the client in the Application Authentication Context Class Reference claim. A value of "0" indicates the end-user authentication did not meet the requirements of ISO/IEC 29115.

Example JWT Value:
"acr": "0"
Authentication Instant Records the date and time when authentication occurred.

Example SAML Value:
<AuthnStatement AuthnInstant="2011-12-29T05:35:22.000Z">
amr Authentication Method Identifies how the subject of the token was authenticated.

Example SAML Value:

Example JWT Value: “amr”: ["pwd"]
given_name First Name Provides the first or "given" name of the user, as set on the Azure AD user object.

Example SAML Value:
<Attribute Name=””>

Example JWT Value:
"given_name": "Frank"
groups Groups Provides object IDs that represent the subject's group memberships. These values are unique (see Object ID) and can be safely used for managing access, such as enforcing authorization to access a resource. The groups included in the groups claim are configured on a per-application basis, through the "groupMembershipClaims" property of the application manifest. A value of null will exclude all groups, a value of "SecurityGroup" will include only Active Directory Security Group memberships, and a value of "All" will include both Security Groups and Office 365 Distribution Lists.

Example SAML Value:
<Attribute Name="">

Example JWT Value:
“groups”: ["0e129f5b-6b0a-4944-982d-f776045632af", … ]
idp Identity Provider Records the identity provider that authenticated the subject of the token. This value is identical to the value of the Issuer claim unless the user account is in a different tenant than the issuer.

Example SAML Value:
<Attribute Name=””>

Example JWT Value:
iat IssuedAt Stores the time at which the token was issued. It is often used to measure token freshness.

Example SAML Value:
<Assertion ID="_d5ec7a9b-8d8f-4b44-8c94-9812612142be" IssueInstant="2014-01-06T20:20:23.085Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">

Example JWT Value:
"iat": 1390234181
iss Issuer Identifies the security token service (STS) that constructs and returns the token. In the tokens that Azure AD returns, the issuer is The GUID in the Issuer claim value is the tenant ID of the Azure AD directory. The tenant ID is an immutable and reliable identifier of the directory.

Example SAML Value:

Example JWT Value:
family_name Last Name Provides the last name, surname, or family name of the user as defined in the Azure AD user object.

Example SAML Value:
<Attribute Name=””>

Example JWT Value:
"family_name": "Miller"
unique_name Name Provides a human readable value that identifies the subject of the token. This value is not guaranteed to be unique within a tenant and is designed to be used only for display purposes.

Example SAML Value:
<Attribute Name=””>

Example JWT Value:
"unique_name": ""
oid Object ID Contains a unique identifier of an object in Azure AD. This value is immutable and cannot be reassigned or reused. Use the object ID to identify an object in queries to Azure AD.

Example SAML Value:
<Attribute Name="">

Example JWT Value:
roles Roles Represents all application roles that the subject has been granted both directly and indirectly through group membership and can be used to enforce role-based access control. Application roles are defined on a per-application basis, through the appRoles property of the application manifest. The value property of each application role is the value that appears in the roles claim.

Example SAML Value:
<Attribute Name="">

Example JWT Value:
“roles”: ["Admin", … ]
scp Scope Indicates the impersonation permissions granted to the client application. The default permission is user_impersonation. The owner of the secured resource can register additional values in Azure AD.

Example JWT Value:
"scp": "user_impersonation"
sub Subject Identifies the principal about which the token asserts information, such as the user of an application. This value is immutable and cannot be reassigned or reused, so it can be used to perform authorization checks safely. Because the subject is always present in the tokens the Azure AD issues, we recommended using this value in a general purpose authorization system.
SubjectConfirmation is not a claim. It describes how the subject of the token is verified. Bearer indicates that the subject is confirmed by their possession of the token.

Example SAML Value:
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />

Example JWT Value:
tid Tenant ID An immutable, non-reusable identifier that identifies the directory tenant that issued the token. You can use this value to access tenant-specific directory resources in a multi-tenant application. For example, you can use this value to identify the tenant in a call to the Graph API.

Example SAML Value:
<Attribute Name=””>

Example JWT Value:
nbf, exp Token Lifetime Defines the time interval within which a token is valid. The service that validates the token should verify that the current date is within the token lifetime, else it should reject the token. The service might allow for up to five minutes beyond the token lifetime range to account for any differences in clock time ("time skew") between Azure AD and the service.

Example SAML Value:

Example JWT Value:
"nbf":1363289634, "exp":1363293234
upn User Principal Name Stores the user name of the user principal.

Example JWT Value:
ver Version Stores the version number of the token.

Example JWT Value:
"ver": "1.0"

Access tokens

Upon successful authentication, Azure AD returns an access token, which can be used to access protected resources. The access token is a base 64 encoded JSON Web Token (JWT) and its contents can be inspected by running it through a decoder.

If your app only uses access tokens to get access to APIs, you can (and should) treat access tokens as completely opaque - they are just strings which your app can pass to resources in HTTP requests.

When you request an access token, Azure AD also returns some metadata about the access token for your app's consumption. This information includes the expiry time of the access token and the scopes for which it is valid. This allows your app to perform intelligent caching of access tokens without having to parse open the access token itself.

If your app is an API protected with Azure AD that expects access tokens in HTTP requests, then you should perform validation and inspection of the tokens you receive. Your app should perform validation of the access token before using it to access resources. For more information on validation, please see Validating Tokens.
For details on how to do this with .NET, see Protect a Web API using Bearer tokens from Azure AD.

Refresh tokens

Refresh tokens are security tokens, which your app can use to acquire new access tokens in an OAuth 2.0 flow. It allows your app to achieve long-term access to resources on behalf of a user without requiring interaction by the user.

Refresh tokens are multi-resource. That is to say that a refresh token received during a token request for one resource can be redeemed for access tokens to a completely different resource. To do this, set the resource parameter in the request to the targeted resource.

Refresh tokens are completely opaque to your app. They are long-lived, but your app should not be written to expect that a refresh token will last for any period of time. Refresh tokens can be invalidated at any moment in time for a variety of reasons. The only way for your app to know if a refresh token is valid is to attempt to redeem it by making a token request to Azure AD token endpoint.

When you redeem a refresh token for a new access token, you will receive a new refresh token in the token response. You should save the newly issued refresh token, replacing the one you used in the request. This will guarantee that your refresh tokens remain valid for as long as possible.

Validating tokens

In order to validate an id_token or an access_token, your app should validate both the token's signature and the claims. In order to validate access tokens, your app should also validate the issuer, the audience and the signing tokens. These need to be validated against the values in the OpenID discovery document. For example, the tenant independent version of the document is located at Azure AD middleware has built-in capabilities for validating access tokens, and you can browse through our samples to find one in the language of your choice. For more information on how to explicitly validate a JWT token, please see the manual JWT validation sample.

We provide libraries and code samples that show how to easily handle token validation - the below information is simply provided for those who wish to understand the underlying process. There are also several third party open source libraries available for JWT validation - there is at least one option for almost every platform and language out there. For more information about Azure AD authentication libraries and code samples, please see Azure AD authentication libraries.

Validating the signature

A JWT contains three segments, which are separated by the . character. The first segment is known as the header, the second as the body, and the third as the signature. The signature segment can be used to validate the authenticity of the token so that it can be trusted by your app.

Tokens issued by Azure AD are signed using industry standard asymmetric encryption algorithms, such as RSA 256. The header of the JWT contains information about the key and encryption method used to sign the token:

  "typ": "JWT",
  "alg": "RS256",
  "x5t": "kriMPdmBvx68skT8-mPAB3BseeA"

The alg claim indicates the algorithm that was used to sign the token, while the x5t claim indicates the particular public key that was used to sign 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 your app should be written 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.

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


Try this URL in a browser!

This metadata document is a JSON object containing several useful pieces of information, such as the location of the various endpoints required for performing OpenID Connect authentication.

It also includes a jwks_uri, which gives the location of the set of public keys used to sign tokens. The JSON document located at the jwks_uri contains all of the public key information in use at that particular moment in time. Your app can use the kid claim in the JWT header to select which public key in this document has been used to sign a particular token. It can then perform signature validation using the correct public key and the indicated algorithm.

Performing signature validation is outside the scope of this document - there are many open source libraries available for helping you do so if necessary.

Validating the claims

When your app receives a token (either an id_token upon user sign-in, or an access token as a bearer token in the HTTP request) it should also perform a few checks against the claims in the token. These include but are not limited to:

  • The Audience claim - to verify that the token was intended to be given to your app.
  • The Not Before and Expiration Time claims - to verify that the token has not expired.
  • The Issuer claim - to verify that the token was indeed issued to your app by Azure AD.
  • The Nonce - to mitigate a token replay attack.
  • and more...

For a full list of claim validations your app should perform for ID Tokens, refer to the OpenID Connect specification. Details of the expected values for these claims are included in the preceding id_token section section.

Sample Tokens

This section displays samples of SAML and JWT tokens that Azure AD returns. These samples let you see the claims in context.

SAML Token

This is a sample of a typical SAML token.

<?xml version="1.0" encoding="UTF-8"?>
<t:RequestSecurityTokenResponse xmlns:t="">
    <wsu:Created xmlns:wsu="">2014-12-24T05:15:47.060Z</wsu:Created>
    <wsu:Expires xmlns:wsu="">2014-12-24T06:15:47.060Z</wsu:Expires>
  <wsp:AppliesTo xmlns:wsp="">
    <EndpointReference xmlns="">
    <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_3ef08993-846b-41de-99df-b7f3ff77671b" IssueInstant="2014-12-24T05:20:47.060Z" Version="2.0">
      <ds:Signature xmlns:ds="">
          <ds:CanonicalizationMethod Algorithm="" />
          <ds:SignatureMethod Algorithm="" />
          <ds:Reference URI="#_3ef08993-846b-41de-99df-b7f3ff77671b">
              <ds:Transform Algorithm="" />
              <ds:Transform Algorithm="" />
            <ds:DigestMethod Algorithm="" />
        <KeyInfo xmlns="">
        <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">m_H3naDei2LNxUmEcWd0BZlNi_jVET1pMLR6iQSuYmo</NameID>
        <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />
      <Conditions NotBefore="2014-12-24T05:15:47.060Z" NotOnOrAfter="2014-12-24T06:15:47.060Z">
        <Attribute Name="">
        <Attribute Name="">
        <Attribute Name="">
        <Attribute Name="">
        <Attribute Name="">
        <Attribute Name="">
        <Attribute Name="">
      <AuthnStatement AuthnInstant="2014-12-23T18:51:11.000Z">
    <SecurityTokenReference xmlns="" xmlns:d3p1="" d3p1:TokenType="">
      <KeyIdentifier ValueType="">_3ef08993-846b-41de-99df-b7f3ff77671b</KeyIdentifier>
    <SecurityTokenReference xmlns="" xmlns:d3p1="" d3p1:TokenType="">
      <KeyIdentifier ValueType="">_3ef08993-846b-41de-99df-b7f3ff77671b</KeyIdentifier>

JWT Token - User Impersonation

This is a sample of a typical JSON web token (JWT) used in an authorization code grant flow. In addition to claims, the token includes a version number in ver and appidacr, the authentication context class reference, which indicates how the client was authenticated. For a public client, the value is 0. If a client ID or client secret was used, the value is 1.

 typ: "JWT",
 alg: "RS256",
 x5t: "kriMPdmBvx68skT8-mPAB3BseeA"
 aud: "",
 iss: "",
 iat: 1416968588,
 nbf: 1416968588,
 exp: 1416972488,
 ver: "1.0",
 tid: "b9411234-09af-49c2-b0c3-653adc1f376e",
 amr: [
 roles: [
 oid: "6526e123-0ff9-4fec-ae64-a8d5a77cf287",
 upn: "",
 unique_name: "",
 sub: "yf8C5e_VRkR1egGxJSDt5_olDFay6L5ilBA81hZhQEI",
 family_name: "User",
 given_name: "Sample",
 groups: [
 appid: "b075ddef-0efa-123b-997b-de1337c29185",
 appidacr: "1",
 scp: "user_impersonation",
 acr: "1"