Skip to content

Commit 0603e64

Browse files
davidmu1davidmu1
committed
split access token reference and conceptual
1 parent 27ad873 commit 0603e64

File tree

3 files changed

+148
-125
lines changed

3 files changed

+148
-125
lines changed

‎articles/active-directory/develop/TOC.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -581,6 +581,12 @@
581581
href: ./howto-restore-app.md
582582
- name: Reference
583583
items:
584+
- name: Token claims reference
585+
items:
586+
- name: Access token
587+
href: access-token-claims-reference.md
588+
- name: SAML token
589+
href: reference-saml-tokens.md
584590
- name: Microsoft Authentication Library (MSAL) reference
585591
displayName: SDK, library, msal, auth
586592
items:
@@ -830,8 +836,6 @@
830836
href: single-sign-on-saml-protocol.md
831837
- name: Sign out (SAML)
832838
href: single-sign-out-saml-protocol.md
833-
- name: SAML tokens
834-
href: reference-saml-tokens.md
835839
- name: Token exchange scenarios
836840
href: scenario-token-exchange-saml-oauth.md
837841
- name: App registration reference

‎articles/active-directory/develop/access-token-claims-reference.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Access token claims reference
3+
description: Claims reference with details on the claims included in access tokens issued by the Microsoft identity platform.
4+
services: active-directory
5+
author: davidmu1
6+
manager: CelesteDG
7+
ms.service: active-directory
8+
ms.subservice: develop
9+
ms.workload: identity
10+
ms.topic: reference
11+
ms.date: 05/26/2023
12+
ms.author: davidmu
13+
ms.custom: aaddev, curation-claims
14+
---
15+
16+
## Access token claims reference
17+
18+
Access tokens are [JSON web tokens (JWT)](https://wikipedia.org/wiki/JSON_Web_Token). JWTs contain the following pieces:
19+
20+
- **Header** - Provides information about how to validate the token including information about the type of token and its signing method.
21+
- **Payload** - Contains all of the important data about the user or application that's attempting to call the service.
22+
- **Signature** - Is the raw material used to validate the token.
23+
24+
Each piece is separated by a period (`.`) and separately Base64 encoded.
25+
26+
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](v2-oauth2-client-creds-grant-flow.md) flows are on behalf of applications that don't have names). Claims used for access token validation are always present.
27+
28+
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.
29+
30+
### Header claims
31+
32+
| Claim | Format | Description |
33+
|-------|--------|-------------|
34+
| `typ` | String - always `JWT` | Indicates that the token is a JWT.|
35+
| `alg` | String | Indicates the algorithm used to sign the token, for example, `RS256`. |
36+
| `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. |
37+
| `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. |
38+
39+
### Payload claims
40+
41+
| Claim | Format | Description | Authorization considerations |
42+
|-------|--------|-------------|------------------------------|
43+
| `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. |
44+
| `iss` | String, a security token service (STS) URI | Identifies the STS that constructs and returns the token, and the Azure AD 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. |
45+
|`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 an Azure AD tenant), the `idp` claim may be 'live.com' or an STS URI containing the Microsoft account tenant `9188040d-6c67-4c5b-b112-36a304b66dad`. | |
46+
| `iat` | int, a Unix timestamp | Specifies when the authentication for this token occurred. | |
47+
| `nbf` | int, a Unix timestamp | Specifies the time after which the JWT can be processed. | |
48+
| `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. | |
49+
| `aio` | Opaque String | An internal claim used by Azure AD to record data for token reuse. Resources shouldn't use this claim. | |
50+
| `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. | |
51+
| `amr` | JSON array of strings, only present in v1.0 tokens | Identifies the authentication method of the subject of the token. | |
52+
| `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 Azure AD. | `appid` may be used in authorization decisions. |
53+
| `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 Azure AD. | `azp` may be used in authorization decisions. |
54+
| `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`. | |
55+
| `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`. | |
56+
| `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. |
57+
| `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. |
58+
| `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. |
59+
| `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](v2-oauth2-client-creds-grant-flow.md) 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. |
60+
| `wids` | Array of [RoleTemplateID](../roles/permissions-reference.md#all-roles) GUIDs | Denotes the tenant-wide roles assigned to this user, from the section of roles present in [Azure AD built-in roles](../roles/permissions-reference.md#all-roles). The `groupMembershipClaims` property of the [application manifest](reference-app-manifest.md) configures this claim on a per-application basis. Set the claim to `All` or `DirectoryRole`. May not be present in tokens obtained through the implicit flow due to token length concerns. | These values can be used for managing access, such as enforcing authorization to access a resource. |
61+
| `groups` | JSON array of GUIDs | Provides object IDs that represent the group memberships of the subject. The `groupMembershipClaims` property of the [application manifest](reference-app-manifest.md) configures the groups claim on a per-application basis. A value of `null` excludes all groups, a value of `SecurityGroup` includes only Active Directory Security Group memberships, and a value of `All` includes both Security Groups and Microsoft 365 Distribution Lists. <br><br>See the `hasgroups` claim for details on using the `groups` claim with the implicit grant. For other flows, if the number of groups the user is in goes over 150 for SAML and 200 for JWT, then Azure AD 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. |
62+
| `hasgroups` | Boolean | If present, always `true`, indicates whether the user is in at least one group. Used in place of the `groups` claim for JWTs in implicit grant flows if the full groups claim would extend the URI fragment beyond the URL length limits (currently six or more groups). 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. | |
63+
| `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. <br><br>**Example JWT Value**: <br> `"groups":"src1"` <br> `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` | |
64+
| `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. |
65+
| `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. |
66+
| `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. |
67+
| `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. |
68+
| `uti` | String | Token identifier claim, equivalent to `jti` in the JWT specification. Unique, per-token identifier that is case-sensitive. | |
69+
| `rh` | Opaque String | An internal claim used by Azure to revalidate tokens. Resources shouldn't use this claim. | |
70+
| `ver` | String, either `1.0` or `2.0` | Indicates the version of the access token. | |
71+
| `xms_cc` | JSON array of strings | Indicates whether the client application that acquired the token is capable of handling claims challenges. This claim is commonly used in Conditional Access and Continuous Access Evaluation scenarios. The resource server that the token is issued for controls the presence of the claim in it. For example, a service application. For more information, see [Claims challenges, claims requests and client capabilities](claims-challenge.md?tabs=dotnet). Resource servers should check this claim in access tokens received from client applications. If this claim is present, resource servers can respond back with a claims challenge. The claims challenge requests more claims in a new access token to authorize access to a protected resource. |
72+
73+
#### Groups overage claim
74+
75+
Azure AD 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, and only 6 if issued by using the implicit flow), then Azure AD 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.
76+
77+
```JSON
78+
{
79+
...
80+
"_claim_names": {
81+
"groups": "src1"
82+
},
83+
"_claim_sources": {
84+
"src1": {
85+
"endpoint": "[Url to get this user's group membership from]"
86+
}
87+
}
88+
...
89+
}
90+
```
91+
92+
Use the `BulkCreateGroups.ps1` provided in the [App Creation Scripts](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/5-WebApp-AuthZ/5-2-Groups/AppCreationScripts) folder to help test overage scenarios.
93+
94+
#### v1.0 basic claims
95+
96+
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](active-directory-optional-claims.md).
97+
98+
| Claim | Format | Description |
99+
|-------|--------|-------------|
100+
| `ipaddr`| String | The IP address the user authenticated from. |
101+
| `onprem_sid`| String, in [SID format](/windows/desktop/SecAuthZ/sid-components) | In cases where the user has an on-premises authentication, this claim provides their SID. Use this claim for authorization in legacy applications. |
102+
| `pwd_exp`| int, a Unix timestamp | Indicates when the user's password expires. |
103+
| `pwd_url`| String | A URL where users can reset their password. |
104+
| `in_corp`| boolean | Signals if the client is signing in from the corporate network. |
105+
| `nickname`| String | Another name for the user, separate from first or last name.|
106+
| `family_name` | String | Provides the last name, surname, or family name of the user as defined on the user object. |
107+
| `given_name` | String | Provides the first or given name of the user, as set on the user object. |
108+
| `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. |
109+
110+
#### amr claim
111+
112+
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.
113+
114+
| Value | Description |
115+
|-----|-------------|
116+
| `pwd` | Password authentication, either a user's Microsoft password or a client secret of an application. |
117+
| `rsa` | Authentication was based on the proof of an RSA key, for example with the [Microsoft Authenticator app](https://aka.ms/AA2kvvu). This value also indicates the use of a self-signed JWT with a service owned X509 certificate in authentication. |
118+
| `otp` | One-time passcode using an email or a text message. |
119+
| `fed` | Indicates the use of a federated authentication assertion (such as JWT or SAML). |
120+
| `wia` | Windows Integrated Authentication |
121+
| `mfa` | Indicates the use of [Multi-factor authentication](../authentication/concept-mfa-howitworks.md). Includes the other authentication methods when this claim is present. |
122+
| `ngcmfa` | Equivalent to `mfa`, used for provisioning of certain advanced credential types. |
123+
| `wiaormfa`| The user used Windows or an MFA credential to authenticate. |
124+
| `none` | Indicates no completed authentication. |
125+
126+
## Next steps
127+
128+
- Learn more about the [access tokens used in Azure AD](access-tokens.md).

0 commit comments

Comments
 (0)