Access token claims reference

Access tokens are JSON web tokens (JWT). JWTs contain the following pieces:

• Header - Provides information about how to validate the token including information about the type of token and its signing method.
• Payload - Contains all of the important data about the user or application that's attempting to call the service.
• Signature - Is the raw material used to validate the token.

Each piece is separated by a period (.) and separately Base 64 encoded.

Claims are present only if a value exists to fill it. An application shouldn't take a dependency on a claim being present. Examples include pwd_exp (not every tenant requires passwords to expire) and family_name (client credential flows are on behalf of applications that don't have names). The access token will always contain sufficient claims for access evaluation.

The Microsoft identity platform uses some claims to help secure tokens for reuse. The description of Opaque marks these claims as not being for public consumption. These claims may or may not appear in a token, and new ones may be added without notice.

Header claims

Claim	Format	Description
typ	String - always JWT	Indicates that the token is a JWT.
alg	String	Indicates the algorithm used to sign the token, for example, RS256.
kid	String	Specifies the thumbprint for the public key used for validating the signature of the token. Emitted in both v1.0 and v2.0 access tokens.
x5t	String	Functions the same (in use and value) as kid. x5t and is a legacy claim emitted only in v1.0 access tokens for compatibility purposes.

Payload claims

Claim	Format	Description	Authorization considerations
acrs	JSON array of strings	Indicates the Auth Context IDs of the operations that the bearer is eligible to perform. Auth Context IDs can be used to trigger a demand for step-up authentication from within your application and services. Often used along with the xms_cc claim.
aud	String, an Application ID URI or GUID	Identifies the intended audience of the token. In v2.0 tokens, this value is always the client ID of the API. In v1.0 tokens, it can be the client ID or the resource URI used in the request. The value can depend on how the client requested the token.	This value must be validated, reject the token if the value doesn't match the intended audience.
iss	String, a security token service (STS) URI	Identifies the STS that constructs and returns the token, and the Microsoft Entra tenant of the authenticated user. If the token issued is a v2.0 token (see the ver claim), the URI ends in /v2.0. The GUID that indicates that the user is a consumer user from a Microsoft account is 9188040d-6c67-4c5b-b112-36a304b66dad.	The application can use the GUID portion of the claim to restrict the set of tenants that can sign in to the application, if applicable.
idp	String, usually an STS URI	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 isn't in the same tenant as the issuer, such as guests. Use the value of iss if the claim isn't present. For personal accounts being used in an organizational context (for instance, a personal account invited to a Microsoft Entra tenant), the idp claim may be 'live.com' or an STS URI containing the Microsoft account tenant 9188040d-6c67-4c5b-b112-36a304b66dad.
iat	int, a Unix timestamp	Specifies when the authentication for this token occurred.
nbf	int, a Unix timestamp	Specifies the time after which the JWT can be processed.
exp	int, a Unix timestamp	Specifies the expiration time before which the JWT can be accepted for processing. A resource may reject the token before this time as well. The rejection can occur for a required change in authentication or when a token is revoked.
aio	Opaque String	An internal claim used by Microsoft Entra ID to record data for token reuse. Resources shouldn't use this claim.
acr	String, a 0 or 1, only present in v1.0 tokens	A value of 0 for the "Authentication context class" claim indicates the end-user authentication didn't meet the requirements of ISO/IEC 29115.
amr	JSON array of strings, only present in v1.0 tokens	Identifies the authentication method of the subject of the token.
appid	String, a GUID, only present in v1.0 tokens	The application ID of the client using the token. 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 Microsoft Entra ID.	appid may be used in authorization decisions.
azp	String, a GUID, only present in v2.0 tokens	A replacement for appid. The application ID of the client using the token. 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 Microsoft Entra ID.	azp may be used in authorization decisions.
appidacr	String, a 0, 1, or 2, only present in v1.0 tokens	Indicates authentication method of the client. For a public client, the value is 0. When you use the client ID and client secret, the value is 1. When you use a client certificate for authentication, the value is 2.
azpacr	String, a 0, 1, or 2, only present in v2.0 tokens	A replacement for appidacr. Indicates the authentication method of the client. For a public client, the value is 0. When you use the client ID and client secret, the value is 1. When you use a client certificate for authentication, the value is 2.
preferred_username	String, only present in v2.0 tokens.	The primary username that represents the user. The value could be an email address, phone number, or a generic username without a specified format. Use the value for username hints and in human-readable UI as a username. To receive this claim, use the profile scope.	Since this value is mutable, don't use it to make authorization decisions.
name	String	Provides a human-readable value that identifies the subject of the token. The value can vary, it's mutable, and is for display purposes only. To receive this claim, use the profile scope.	Don't use this value to make authorization decisions.
scp	String, a space separated list of scopes	The set of scopes exposed by the application for which the client application has requested (and received) consent. Only included for user tokens.	The application should verify that these scopes are valid ones exposed by the application, and make authorization decisions based on the value of these scopes.
roles	Array of strings, a list of permissions	The set of permissions exposed by the application that the requesting application or user has been given permission to call. The client credential flow uses this set of permission in place of user scopes for application tokens. For user tokens, this set of values contains the assigned roles of the user on the target application.	These values can be used for managing access, such as enforcing authorization to access a resource.
wids	Array of RoleTemplateID GUIDs	Denotes the tenant-wide roles assigned to this user, from the section of roles present in Microsoft Entra built-in roles. The groupMembershipClaims property of the application manifest configures this claim on a per-application basis. Set the claim to All or DirectoryRole.	These values can be used for managing access, such as enforcing authorization to access a resource.
groups	JSON array of GUIDs	Provides object IDs that represent the group memberships of the subject. The groupMembershipClaims property of the application manifest configures the groups claim on a per-application basis. A value of null excludes all groups, a value of SecurityGroup includes directory roles and Active Directory Security Group memberships, and a value of All includes both Security Groups and Microsoft 365 Distribution Lists. For other flows, if the number of groups the user is in goes over 150 for SAML and 200 for JWT, then Microsoft Entra ID adds an overage claim to the claim sources. The claim sources point to the Microsoft Graph endpoint that contains the list of groups for the user.	These values can be used for managing access, such as enforcing authorization to access a resource.
hasgroups	Boolean	If present, always true, indicates whether the user is in at least one group. Indicates that the client should use the Microsoft Graph API to determine the groups (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) of the user.
groups:src1	JSON object	Includes a link to the full groups list for the user when token requests are too large for the token. For JWTs as a distributed claim, for SAML as a new claim in place of the groups claim. Example JWT Value: "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub	String	The principal associated with the token. For example, the user of an application. This value is immutable, don't reassign or reuse. The subject is a pairwise identifier that's unique to a particular application ID. If a single user signs into two different applications using two different client IDs, those applications receive two different values for the subject claim. Using the two different values depends on architecture and privacy requirements. See also the oid claim, which does remain the same across applications within a tenant.	This value can be used to perform authorization checks, such as when the token is used to access a resource, and can be used as a key in database tables.
oid	String, a GUID	The immutable identifier for the requestor, which is the verified identity of the user or service principal. This ID uniquely identifies the requestor across applications. Two different applications signing in the same user receive the same value in the oid claim. The oid can be used when making queries to Microsoft online services, such as the Microsoft Graph. The Microsoft Graph returns this ID as the id property for a given user account. Because the oid allows multiple applications to correlate principals, to receive this claim for users use the profile scope. If a single user exists in multiple tenants, the user contains a different object ID in each tenant. Even though the user logs into each account with the same credentials, the accounts are different.	This value can be used to perform authorization checks, such as when the token is used to access a resource, and can be used as a key in database tables.
tid	String, a GUID	Represents the tenant that the user is signing in to. For work and school accounts, the GUID is the immutable tenant ID of the organization that the user is signing in to. For sign-ins to the personal Microsoft account tenant (services like Xbox, Teams for Life, or Outlook), the value is 9188040d-6c67-4c5b-b112-36a304b66dad. To receive this claim, the application must request the profile scope.	This value should be considered in combination with other claims in authorization decisions.
unique_name	String, only present in v1.0 tokens	Provides a human readable value that identifies the subject of the token.	This value can be different within a tenant and use it only for display purposes.
uti	String	Token identifier claim, equivalent to jti in the JWT specification. Unique, per-token identifier that is case-sensitive.
rh	Opaque String	An internal claim used by Azure to revalidate tokens. Resources shouldn't use this claim.
ver	String, either 1.0 or 2.0	Indicates the version of the access token.
xms_cc	JSON array of strings	Indicates whether the client application that acquired the token is capable of handling claims challenges. It's often used along with claim acrs. This claim is commonly used in Conditional Access and Continuous Access Evaluation scenarios. The resource server or service application that the token is issued for controls the presence of this claim in a token. A value of cp1 in the access token is the authoritative way to identify that a client application is capable of handling a claims challenge. For more information, see Claims challenges, claims requests and client capabilities.

Note

The roles, groups, scp, and wids claims are not an exhaustive list of how a resource might authorize a user or application, nor are they an exhaustive list of permissions granted to the caller. The target resource may use another method to authorize access to its protected resources.

Groups overage claim

Microsoft Entra ID limits the number of object IDs that it includes in the groups claim to stay within the size limit of the HTTP header. If a user is a member of more groups than the overage limit (150 for SAML tokens, 200 for JWT tokens), then Microsoft Entra ID doesn't emit the groups claim in the token. Instead, it includes an overage claim in the token that indicates to the application to query the Microsoft Graph API to retrieve the group membership of the user.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Use the BulkCreateGroups.ps1 provided in the App Creation Scripts folder to help test overage scenarios.

Note

The URL returned will be an Azure AD Graph URL (that is, graph.windows.net). Instead of relying on this URL, services should instead use the idtyp optional claim (which identifies whether the token is an app or app+user token) to construct a Microsoft Graph URL for querying the full list of groups.

v1.0 basic claims

The v1.0 tokens include the following claims if applicable, but not v2.0 tokens by default. To use these claims for v2.0, the application requests them using optional claims.

Claim	Format	Description
ipaddr	String	The IP address the user authenticated from.
onprem_sid	String, in SID format	In cases where the user has an on-premises authentication, this claim provides their SID. Use this claim for authorization in legacy applications.
pwd_exp	int, a Unix timestamp	Indicates when the user's password expires.
pwd_url	String	A URL where users can reset their password.
in_corp	boolean	Signals if the client is signing in from the corporate network.
nickname	String	Another name for the user, separate from first or last name.
family_name	String	Provides the last name, surname, or family name of the user as defined on the user object.
given_name	String	Provides the first or given name of the user, as set on the user object.
upn	String	The username of the user. May be a phone number, email address, or unformatted string. Only use for display purposes and providing username hints in reauthentication scenarios.

amr claim

Identities can authenticate in different ways, which may be relevant to the application. The amr claim is an array that can contain multiple items, such as ["mfa", "rsa", "pwd"], for an authentication that used both a password and the Authenticator app.

Value	Description
pwd	Password authentication, either a user's Microsoft password or a client secret of an application.
rsa	Authentication was based on the proof of an RSA key, for example with the Microsoft Authenticator app. This value also indicates the use of a self-signed JWT with a service owned X509 certificate in authentication.
otp	One-time passcode using an email or a text message.
fed	Indicates the use of a federated authentication assertion (such as JWT or SAML).
wia	Windows Integrated Authentication
mfa	Indicates the use of Multifactor authentication. Includes the other authentication methods when this claim is present.
ngcmfa	Equivalent to mfa, used for provisioning of certain advanced credential types.
wiaormfa	The user used Windows or an MFA credential to authenticate.
none	Indicates no completed authentication.

Next steps

• Learn more about the access tokens used in Microsoft Entra ID.