Microsoft 标识平台访问令牌Microsoft identity platform access tokens

客户端可以使用访问令牌安全调用受 Azure 保护的 API。Access tokens enable clients to securely call APIs protected by Azure. Microsoft 标识平台访问令牌为 JWT,即 Azure 签名的 Base64 编码 JSON 对象。Microsoft identity platform access tokens are JWTs, Base64 encoded JSON objects signed by Azure. 客户端应将访问令牌视为不透明的字符串,作为令牌的内容仅适用于资源。Clients should treat access tokens as opaque strings, as the contents of the token are intended for the resource only. 在验证和调试时,开发人员可以使用 jwt.ms 等站点来解码 JWT。For validation and debugging purposes, developers can decode JWTs using a site like jwt.ms. 客户端可以使用各种协议从 v1.0 终结点或 v2.0 终结点获取访问令牌。Your client can get an access token from either the v1.0 endpoint or the v2.0 endpoint using a variety of protocols.

当客户端请求访问令牌时,Azure AD 还是会返回一些有关访问令牌的元数据以供应用使用。When your client requests 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's valid. 此数据可让应用执行访问令牌的智能缓存,而无需分析访问令牌本身。This data allows your app to do intelligent caching of access tokens without having to parse the access token itself.

如果应用程序是客户端可以请求访问的资源 (Web API),则访问令牌会提供可在身份验证和授权中使用的有用信息,例如用户、客户端、颁发者、权限,等等。If your application is a resource (web API) that clients can request access to, access tokens provide helpful information for use in authentication and authorization, such as the user, client, issuer, permissions, and more.

请参阅以下部分,了解资源如何验证和使用访问令牌中的声明。See the following sections to learn how a resource can validate and use the claims inside an access token.

Important

访问令牌是根据令牌的受众(即,拥有令牌中范围的应用程序)创建的。 Access tokens are created based on the audience of the token, meaning the application that owns the scopes in the token. 如果在应用清单中将资源设置 accessTokenAcceptedVersion 指定为 2,则允许客户端调用 v1.0 终结点来接收 v2.0 访问令牌。This is how a resource setting accessTokenAcceptedVersion in the app manifest to 2 allows a client calling the v1.0 endpoint to receive a v2.0 access token. 同样,这就是为什么更改客户端的访问令牌可选声明不会更改为 user.read 请求令牌时收到的访问令牌的原因,该令牌归 MS Graph 资源所有。Similarly, this is why changing the access token optional claims for your client do not change the access token received when a token is requested for user.read, which is owned by the MS Graph resource.

示例令牌Sample tokens

v1.0 和 v2.0 令牌很相似,都包含许多相同的声明。v1.0 and v2.0 tokens look similar and contain many of the same claims. 此处提供了每种令牌的示例。An example of each is provided here.

v1.0v1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0=.D3H6pMUtQnoJAGq6AHd

JWT.ms 中查看此 v1.0 令牌。View this v1.0 token in JWT.ms.

v2.0v2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

JWT.ms 中查看此 v2.0 令牌。View this v2.0 token in JWT.ms.

访问令牌中的声明Claims in access tokens

JWT 拆分成三个部分:JWTs are split into three pieces:

  • 标头 - 提供有关如何验证令牌的信息,包括有关令牌的类型及其签名方式的信息。Header - Provides information about how to validate the token including information about the type of token and how it was signed.
  • 有效负载 - 包含有关正在尝试调用你的服务的用户或应用的所有重要数据。Payload - Contains all of the important data about the user or app that is attempting to call your service.
  • 签名 - 用于验证令牌的原始材料。Signature - Is the raw material used to validate the token.

每个部分由句点 (.) 分隔,并分别采用 Base64 编码。Each piece is separated by a period (.) and separately Base64 encoded.

仅当存在可以填充声明的值时,才提供声明。Claims are present only if a value exists to fill it. 因此,应用不应该依赖于所要提供的声明。So, your app shouldn't take a dependency on a claim being present. 示例包括 pwd_exp(并非每个租户都要求密码过期)或 family_name客户端凭据流代表无名称的应用程序)。Examples include pwd_exp (not every tenant requires passwords to expire) or family_name (client credential flows are on behalf of applications, which don't have names). 始终会提供用于验证访问令牌的声明。Claims used for access token validation will always be present.

Note

某些声明用于帮助 Azure AD 保护重复使用的令牌。Some claims are used to help Azure AD secure tokens in case of reuse. 在说明中,这些声明标记为“不透明”,表示不可公开使用。These are marked as not being for public consumption in the description as "Opaque". 这些声明不一定会显示在令牌中,我们可能在不发出通告的情况下添加新的声明。These claims may or may not appear in a token, and new ones may be added without notice.

标头声明Header claims

声明Claim 格式Format 说明Description
typ 字符串 - 始终为“JWT”String - always "JWT" 指示令牌是 JWT。Indicates that the token is a JWT.
nonce StringString 用于防范令牌重放攻击的唯一标识符。A unique identifier used to protect against token replay attacks. 资源可以记录此值以防范重放攻击。Your resource can record this value to protect against replays.
alg StringString 指示用于对令牌进行签名的算法,例如“RS256”Indicates the algorithm that was used to sign the token, for example, "RS256"
kid StringString 指定用于对此令牌进行签名的公钥的指纹。Specifies the thumbprint for the public key that's used to sign this token. 在 v1.0 和 v2.0 访问令牌中已发出。Emitted in both v1.0 and v2.0 access tokens.
x5t StringString 功能与 kid 相同(在用法和值方面)。Functions the same (in use and value) as kid. x5t 是在 v1.0 访问令牌中仅出于兼容目的而发出的旧式声明。x5t is a legacy claim emitted only in v1.0 access tokens for compatibility purposes.

有效负载声明Payload claims

声明Claim 格式Format 说明Description
aud 字符串,应用 ID URIString, an App ID URI 标识令牌的目标接收方。Identifies the intended recipient of the token. 在访问令牌中,受众是在 Azure 门户中分配给应用的应用程序 ID。In access tokens, the audience is your app's Application ID, assigned to your app in the Azure portal. 应用应该验证此值并拒绝其值不匹配的令牌。Your app should validate this value and reject the token if the value does not match.
iss 字符串,STS URIString, an STS URI 标识构造并返回令牌的安全令牌服务 (STS),以及对用户进行身份验证的 Azure AD 租户。Identifies the security token service (STS) that constructs and returns the token, and the Azure AD tenant in which the user was authenticated. 如果颁发的令牌是 v2.0 令牌(请参阅 ver 声明),则 URI 将以 /v2.0 结尾。If the token issued is a v2.0 token (see the ver claim), the URI will end in /v2.0. 应用应该使用声明的 GUID 部分限制可登录应用的租户集(如果适用)。Your app should use the GUID portion of the claim to restrict the set of tenants that can sign in to the app, if applicable.
idp 字符串,通常是 STS URIString, 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 not in the same tenant as the issuer - guests, for instance. 如果声明不存在,则意味着可以改用 iss 的值。If the claim isn't present, it means that the value of iss can be used instead.
iat int,UNIX 时间戳int, a UNIX timestamp “Issued At”表示针对此令牌进行身份验证的时间。"Issued At" indicates when the authentication for this token occurred.
nbf int,UNIX 时间戳int, a UNIX timestamp “nbf”(不早于)声明指定只能在哪个时间之后接受 JWT 的处理。The "nbf" (not before) claim identifies the time before which the JWT must not be accepted for processing.
exp int,UNIX 时间戳int, a UNIX timestamp “exp”(过期时间)声明指定只能在哪个时间(含)之前接受 JWT 的处理。The "exp" (expiration time) claim identifies the expiration time on or after which the JWT must not be accepted for processing. 请务必注意,资源也可以在此时间之前拒绝令牌,例如,需要对身份验证进行更改,或者检测到令牌吊销时。It's important to note that a resource may reject the token before this time as well, such as when a change in authentication is required or a token revocation has been detected.
aio 不透明字符串Opaque String 一个内部声明,Azure AD 用它来记录有关重复使用令牌的数据。An internal claim used by Azure AD to record data for token reuse. 资源不应使用此声明。Resources should not use this claim.
acr 字符串,“0”或“1”String, a "0" or "1" 仅在 v1.0 令牌中提供。Only present in v1.0 tokens. “身份验证上下文类”声明。The "Authentication context class" claim. 值为“0”表示最终用户身份验证不符合 ISO/IEC 29115 要求。A value of "0" indicates the end-user authentication did not meet the requirements of ISO/IEC 29115.
amr 字符串的 JSON 数组JSON array of strings 仅在 v1.0 令牌中提供。Only present in v1.0 tokens. 标识对令牌使用者进行身份验证的方式。Identifies how the subject of the token was authenticated. 有关更多详细信息,请参阅 amr 声明部分See the amr claim section for more details.
appid 字符串,GUIDString, a GUID 仅在 v1.0 令牌中提供。Only present in v1.0 tokens. 使用令牌的客户端的应用程序 ID。The application ID of the client using the token. 该应用程序可以自身名义或者代表用户进行操作。The application can act as itself or on behalf of a user. 应用程序 ID 通常表示应用程序对象,但它还可以表示 Azure AD 中的服务主体对象。The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.
appidacr “0”、“1”或“2”"0", "1", or "2" 仅在 v1.0 令牌中提供。Only present in v1.0 tokens. 表示对客户端进行身份验证的方式。Indicates how the client was authenticated. 对于公共客户端,值为“0”。For a public client, the value is "0". 如果使用客户端 ID 和客户端机密,则值为“1”。If client ID and client secret are used, the value is "1". 如果使用客户端证书进行身份验证,则值为“2”。If a client certificate was used for authentication, the value is "2".
azp 字符串,GUIDString, a GUID 仅在 v2.0 令牌中存在,取代了 appidOnly present in v2.0 tokens, a replacement for appid. 使用令牌的客户端的应用程序 ID。The application ID of the client using the token. 该应用程序可以自身名义或者代表用户进行操作。The application can act as itself or on behalf of a user. 应用程序 ID 通常表示应用程序对象,但它还可以表示 Azure AD 中的服务主体对象。The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.
azpacr “0”、“1”或“2”"0", "1", or "2" 仅在 v2.0 令牌中存在,取代了 appidacrOnly present in v2.0 tokens, a replacement for appidacr. 表示对客户端进行身份验证的方式。Indicates how the client was authenticated. 对于公共客户端,值为“0”。For a public client, the value is "0". 如果使用客户端 ID 和客户端机密,则值为“1”。If client ID and client secret are used, the value is "1". 如果使用客户端证书进行身份验证,则值为“2”。If a client certificate was used for authentication, the value is "2".
preferred_username StringString 表示用户的主用户名。The primary username that represents the user. 可以是电子邮件地址、电话号码或未指定格式的一般用户名。It could be an email address, phone number, or a generic username without a specified format. 其值是可变的,可能随时改变。Its value is mutable and might change over time. 由于此值是可变的,因此它不能用于做出授权决定。Since it is mutable, this value must not be used to make authorization decisions. 但它可以用于用户名提示。It can be used for username hints though. 需要 profile 范围才能接收此声明。The profile scope is required in order to receive this claim.
name StringString 提供一个用户可读值,用于标识令牌使用者。Provides a human-readable value that identifies the subject of the token. 该值不一定唯一,而且可变,只能用于显示目的。The value is not guaranteed to be unique, it is mutable, and it's designed to be used only for display purposes. 需要 profile 范围才能接收此声明。The profile scope is required in order to receive this claim.
scp 字符串,范围的空格分隔列表String, a space separated list of scopes 应用程序公开的、客户端应用程序已请求(和接收)其许可的范围集。The set of scopes exposed by your application for which the client application has requested (and received) consent. 应用应该验证这些范围是否为应用公开的有效范围,并根据这些范围的值做出授权决策。Your app should verify that these scopes are valid ones exposed by your app, and make authorization decisions based on the value of these scopes. 仅为用户令牌包含此值。Only included for user tokens.
roles 字符串数组,权限列表Array of strings, a list of permissions 应用程序公开的、请求方应用程序或用户有权调用的权限集。The set of permissions exposed by your application that the requesting application or user has been given permission to call. 对于应用程序令牌,在执行客户端凭据流期间,将使用此值来取代用户范围。For application tokens, this is used during the client-credentials flow in place of user scopes. 对于用户令牌,此值将填充为在目标应用程序上分配给用户的角色。For user tokens this is populated with the roles the user was assigned to on the target application.
wids RoleTemplateID GUID 的数组Array of RoleTemplateID GUIDs 表示在管理员角色页中的角色部分分配给此用户的租户级角色。Denotes the tenant-wide roles assigned to this user, from the section of roles present in the admin roles page. 此声明是通过应用程序清单groupMembershipClaims 属性按应用程序定义的。This claim is configured on a per-application basis, through the groupMembershipClaims property of the application manifest. 必须将其设置为“All”或“DirectoryRole”。Setting it to "All" or "DirectoryRole" is required. 由于令牌长度方面的原因,它在通过隐式流获取的令牌中可能不存在。May not be present in tokens obtained through the implicit flow due to token length concerns.
groups GUID 的 JSON 数组JSON array of GUIDs 指定表示使用者的组成员身份的对象 ID。Provides object IDs that represent the subject's group memberships. 这些值具有唯一性(请参阅对象 ID),可安全地用于管理访问,例如强制要求授权访问资源。These values are unique (see Object ID) and can be safely used for managing access, such as enforcing authorization to access a resource. 组声明中包含的组通过应用程序清单groupMembershipClaims 属性基于每个应用程序进行配置。The groups included in the groups claim are configured on a per-application basis, through the groupMembershipClaims property of the application manifest. 值为 null 将排除所有组;值为“SecurityGroup”将只包括 Active Directory 安全组成员身份;值为“All”将包括安全组和 Office 365 通讯组列表。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.

有关将 groups 声明与隐式授权一起使用的详细信息,请参阅下文中的 hasgroups 声明。See the hasgroups claim below for details on using the groups claim with the implicit grant.
对于其他流,如果用户所在的组数超出了某个限制(对于 SAML,为 150,对于 JWT,为 200),则会将超额声明添加到指向包含该用户的组列表的 AAD Graph 终结点的声明源。For other flows, if the number of groups the user is in goes over a limit (150 for SAML, 200 for JWT), then an overage claim will be added to the claim sources pointing at the AAD Graph endpoint containing the list of groups for the user.
hasgroups 布尔Boolean 如果存在,始终为 true,表示用户至少在一个组中。If present, always true, denoting the user is in at least one group. 如果完整组声明将导致 URI 片段超出 URL 长度限制(当前为 6 个或更多组),则在隐式授权流中用来替代 JWT 的 groups 声明。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 6 or more groups). 指示客户端应当使用 Graph 来确定用户的组 (https://graph.chinacloudapi.cn/{tenantID}/users/{userID}/getMemberObjects)。Indicates that the client should use the Graph to determine the user's groups (https://graph.chinacloudapi.cn/{tenantID}/users/{userID}/getMemberObjects).
groups:src1 JSON 对象JSON object 对于长度不受限制(参阅上文中的 hasgroups)但对于令牌而言仍然太大的令牌请求,将包括指向用户的完整组列表的链接。For token requests that are not length limited (see hasgroups above) but still too large for the token, a link to the full groups list for the user will be included. 对于 JWT,作为分布式声明;对于 SAML,作为新声明替代 groups 声明。For JWTs as a distributed claim, for SAML as a new claim in place of the groups claim.

JWT 值示例: Example JWT Value:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.chinacloudapi.cn/{tenantID}/users/{userID}/getMemberObjects" }"_claim_sources: "src1" : { "endpoint" : "https://graph.chinacloudapi.cn/{tenantID}/users/{userID}/getMemberObjects" }
sub 字符串,GUIDString, a GUID 令牌针对其断言信息的主体,例如应用的用户。The principal about which the token asserts information, such as the user of an app. 此值固定不变,无法重新分配或重复使用。This value is immutable and cannot be reassigned or reused. 可使用它安全地执行授权检查(例如,使用令牌访问资源时),并可将它用作数据库表中的键。It can be used to perform authorization checks safely, such as when the token is used to access a resource, and can be used as a key in database tables. 由于使用者始终会在 Azure AD 颁发的令牌中存在,我们建议在通用授权系统中使用此值。Because the subject is always present in the tokens that Azure AD issues, we recommend using this value in a general-purpose authorization system. 但是,使用者是成对标识符 - 它对特定应用程序 ID 是唯一的。The subject is, however, a pairwise identifier - it is unique to a particular application ID. 因此,如果单个用户使用两个不同的客户端 ID 登录到两个不同的应用,这些应用将收到两个不同的使用者声明值。Therefore, if a single user signs into two different apps using two different client IDs, those apps will receive two different values for the subject claim. 这不一定是所需的,具体取决于体系结构和隐私要求。This may or may not be desired depending on your architecture and privacy requirements. 另请参阅 oid 声明(在租户中的应用之间确实会保持相同)。See also the oid claim (which does remain the same across apps within a tenant).
oid 字符串,GUIDString, a GUID 在 Microsoft 标识平台中,对象的不可变标识符在这种情况下是用户帐户。The immutable identifier for an object in the Microsoft identity platform, in this case, a user account. 还可以使用它安全地执行授权检查,并将它用作数据库表中的键。It can also be used to perform authorization checks safely and as a key in database tables. 此 ID 唯一标识应用程序中的用户 - 同一个用户登录两个不同的应用程序会在 oid 声明中收到相同值。This ID uniquely identifies the user across applications - two different applications signing in the same user will receive the same value in the oid claim. 因此,对 Microsoft 联机服务(例如 Microsoft Graph)发出查询时可以使用 oidThus, oid can be used when making queries to Microsoft online services, such as the Microsoft Graph. Microsoft Graph 将返回此 ID 作为给定用户帐户的 id 属性。The Microsoft Graph will return this ID as the id property for a given user account. 因为 oid 允许多个应用关联用户,需要 profile 作用域才能收到此声明。Because the oid allows multiple apps to correlate users, the profile scope is required in order to receive this claim. 请注意,如果单个用户存在于多个租户中,该用户将包含每个租户中的不同对象 ID - 它们将视为不同帐户,即使用户使用相同的凭据登录到每个帐户,也是如此。Note that if a single user exists in multiple tenants, the user will contain a different object ID in each tenant - they are considered different accounts, even though the user logs into each account with the same credentials.
tid 字符串,GUIDString, a GUID 表示用户所在的 Azure AD 租户。Represents the Azure AD tenant that the user is from. 对于工作和学校帐户,该 GUID 就是用户所属组织的不可变租户 ID。For work and school accounts, the GUID is the immutable tenant ID of the organization that the user belongs to. 需要 profile 范围才能接收此声明。The profile scope is required in order to receive this claim.
unique_name StringString 仅在 v1.0 令牌中提供。Only present in v1.0 tokens. 提供一个用户可读值,用于标识令牌使用者。Provides a human readable value that identifies the subject of the token. 不保证此值在租户中唯一,只应该用于显示目的。This value is not guaranteed to be unique within a tenant and should be used only for display purposes.
uti 不透明字符串Opaque String Azure 用来重新验证令牌的内部声明。An internal claim used by Azure to revalidate tokens. 资源不应使用此声明。Resources shouldn't use this claim.
rh 不透明字符串Opaque String Azure 用来重新验证令牌的内部声明。An internal claim used by Azure to revalidate tokens. 资源不应使用此声明。Resources should not use this claim.
ver 字符串,1.02.0String, either 1.0 or 2.0 指示访问令牌的版本。Indicates the version of the access token.

v1.0 基本声明v1.0 basic claims

以下声明将包含在 v1.0 令牌中(如果适用),默认不会包含在 v2.0 令牌中。The following claims will be included in v1.0 tokens if applicable, but aren't included in v2.0 tokens by default. 如果使用 v2.0 并需要其中的某个声明,请使用可选声明来请求它们。If you're using v2.0 and need one of these claims, request them using optional claims.

声明Claim 格式Format 说明Description
ipaddr StringString 进行身份验证的用户的来源 IP 地址。The IP address the user authenticated from.
onprem_sid 字符串,采用 SID 格式String, in SID format 如果用户使用了本地身份验证,则此声明会提供其 SID。In cases where the user has an on-premises authentication, this claim provides their SID. 可在旧版应用程序中将 onprem_sid 用于授权。You can use onprem_sid for authorization in legacy applications.
pwd_exp int,UNIX 时间戳int, a UNIX timestamp 指示用户的密码何时过期。Indicates when the user's password expires.
pwd_url StringString 可向用户发送的,以重置其密码的 URL。A URL where users can be sent to reset their password.
in_corp 布尔值boolean 表示客户端是否从企业网络登录。Signals if the client is logging in from the corporate network. 如果不是,则不包括该声明。If they aren't, the claim isn't included.
nickname StringString 用户的附加名称,不同于名字或姓氏。An additional name for the user, separate from first or last name.
family_name StringString 根据用户对象中的定义提供用户的姓氏。Provides the last name, surname, or family name of the user as defined on the user object.
given_name StringString 根据用户对象中的设置提供用户的名字。Provides the first or given name of the user, as set on the user object.
upn StringString 用户的用户名。The username of the user. 可以是电话号码、电子邮件地址或无格式的字符串。May be a phone number, email address, or unformatted string. 只应该用于显示目的,在重新身份验证方案中提供用户名提示。Should only be used for display purposes and providing username hints in reauthentication scenarios.

amr 声明The amr claim

Microsoft 标识可以通过与应用程序相关的不同方式进行身份验证。Microsoft identities can authenticate in different ways, which may be relevant to your application. amr 声明是可以包含多个项(例如 ["mfa", "rsa", "pwd"])的数组,适用于使用密码和 Authenticator 应用的身份验证。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.

ValueValue 说明Description
pwd 密码身份验证,用户的 Microsoft 密码或应用的客户端机密。Password authentication, either a user's Microsoft password or an app's client secret.
rsa 身份验证基于 RSA 密钥的证明,例如,使用 Microsoft Authenticator 应用Authentication was based on the proof of an RSA key, for example with the Microsoft Authenticator app. 这包括,身份验证是否是使用服务拥有的 X509 证书通过自签名的 JWT 执行的。This includes if authentication was done by a self-signed JWT with a service owned X509 certificate.
otp 使用电子邮件或短信的一次性密码。One-time passcode using an email or a text message.
fed 使用了联合身份验证断言(例如 JWT 或 SAML)。A federated authentication assertion (such as JWT or SAML) was used.
wia Windows 集成身份验证Windows Integrated Authentication
mfa 使用了多重身份验证。Multi-factor authentication was used. 如果存在这种情况,则也会包含其他身份验证方法。When this is present the other authentication methods will also be included.
ngcmfa 等效于 mfa,用于预配某些高级凭据类型。Equivalent to mfa, used for provisioning of certain advanced credential types.
wiaormfa 用户已使用 Windows 或 MFA 凭据进行身份验证。The user used Windows or an MFA credential to authenticate.
none 未执行任何身份验证。No authentication was done.

验证令牌Validating tokens

若要验证 id_token 或 access_token,应用应该验证该令牌的签名和声明。To validate an id_token or an access_token, your app should validate both the token's signature and the claims. 若要验证访问令牌,应用还需验证颁发者、受众和签名令牌。To validate access tokens, your app should also validate the issuer, the audience, and the signing tokens. 这些需要根据 OpenID 发现文档中的值进行验证。These need to be validated against the values in the OpenID discovery document. 例如,文档的租户独立版本位于 https://login.partner.microsoftonline.cn/common/.well-known/openid-configurationFor example, the tenant-independent version of the document is located at https://login.partner.microsoftonline.cn/common/.well-known/openid-configuration.

Azure AD 中间件具有验证访问令牌的内置功能,可以浏览我们的示例,以所选语言进行查找。The 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. 有关如何显式验证 JWT 令牌的详细信息,请参阅手动 JWT 验证示例For more information on how to explicitly validate a JWT token, see the manual JWT validation sample.

我们提供了库和代码示例用于演示如何轻松处理令牌验证。We provide libraries and code samples that show how to easily handle token validation. 我们还提供了以下信息以帮助用户了解基础过程。The below information is provided for those who wish to understand the underlying process. 另外还有多个第三方开源库可用于 JWT 验证 - 几乎每个平台和语言都至少有一个选项。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. 有关 Azure AD 身份验证库和代码示例的详细信息,请参阅 v1.0 身份验证库v2.0 身份验证库For more information about Azure AD authentication libraries and code samples, see v1.0 authentication libraries and v2.0 authentication libraries.

验证签名Validating the signature

JWT 包含三个段(以 . 字符分隔)。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.

Azure AD 颁发的令牌已使用行业标准非对称式加密算法(例如 RSA 256)进行签名。Tokens issued by Azure AD are signed using industry standard asymmetric encryption algorithms, such as RSA 256. JWT 的标头包含用于签名令牌的密钥和加密方法的相关信息:The header of the JWT contains information about the key and encryption method used to sign the token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

alg 声明表示用于对令牌进行签名的算法,而 kid 声明表示用于对令牌进行签名的特定公钥。The alg claim indicates the algorithm that was used to sign the token, while the kid claim indicates the particular public key that was used to sign the token.

在任何给定时间点,Azure AD 可以使用特定公钥 - 私钥对中的任何一组对 id_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 定期换用一组可能的密钥,因此应将应用编写成自动处理这些密钥更改。Azure AD rotates the possible set of keys on a periodic basis, so your app should be written to handle those key changes automatically. 对 Azure AD 所用公钥的更新进行检查的合理频率为每 24 小时一次。A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.

可以使用位于以下位置的 OpenID Connect 元数据文档来获取验证签名所需的签名密钥数据:You can acquire the signing key data necessary to validate the signature by using the OpenID Connect metadata document located at:

https://login.partner.microsoftonline.cn/common/v2.0/.well-known/openid-configuration

Tip

在浏览器中尝试打开此 URLTry this URL in a browser!

此元数据文档:This metadata document:

  • 是一个 JSON 对象,其中包含一些有用的信息,例如执行 OpenID Connect 身份验证所需的各种终结点的位置。Is a JSON object containing several useful pieces of information, such as the location of the various endpoints required for doing OpenID Connect authentication.
  • 包含 jwks_uri,提供用于对令牌进行签名的公钥集的位置。Includes a jwks_uri, which gives the location of the set of public keys used to sign tokens. 位于 jwks_uri 的 JSON 文档包含在该特定时间点使用的所有公钥信息。The JSON document located at the jwks_uri contains all of the public key information in use at that particular moment in time. 应用可以使用 JWT 标头中的 kid 声明选择本文档中已用于对特定令牌进行签名的公钥。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 do signature validation using the correct public key and the indicated algorithm.

Note

V1.0 终结点返回 x5tkid 声明,尽管 v2.0 终结点仅使用 kid 声明进行响应。The v1.0 endpoint returns both the x5t and kid claims, while the v2.0 endpoint responds with only the kid claim. 从目前开始,我们建议使用 kid 声明来验证令牌。Going forward, we recommend using the kid claim to validate your token.

执行签名验证超出了本文档的范围 - 有许多开源库可帮助你执行验证(如有必要)。Doing signature validation is outside the scope of this document - there are many open source libraries available for helping you do so if necessary. 但是,Microsoft 标识平台具有标准的一个令牌签名扩展 - 自定义签名密钥。However, the Microsoft Identity platform has one token signing extension to the standards - custom signing keys.

基于声明的授权Claims based authorization

应用程序的业务逻辑将会强制规定此步骤,下面列出了一些常见的授权方法。Your application's business logic will dictate this step, some common authorization methods are laid out below.

  • 检查 scproles 声明,以验证所有现有的范围是否与 API 公开的范围相匹配,并允许客户端执行请求的操作。Check the scp or roles claim to verify that all present scopes match those exposed by your API, and allow the client to do the requested action.
  • 确保允许调用方客户端使用 appid 声明调用你的 API。Ensure the calling client is allowed to call your API using the appid claim.
  • 使用 appidacr 验证调用方客户端的身份验证状态 - 如果不允许公共客户端调用你的 API,则值不应该是 0。Validate the authentication status of the calling client using appidacr - it shouldn't be 0 if public clients aren't allowed to call your API.
  • 根据以往的 nonce 声明列表进行检查,以验证令牌是否未重放。Check against a list of past nonce claims to verify the token isn't being replayed.
  • 检查 tid 是否与允许调用该 API 的租户相匹配。Check that the tid matches a tenant that is allowed to call your API.
  • 使用 acr 声明验证已执行 MFA 的用户。Use the acr claim to verify the user has performed MFA.
  • 如果在访问令牌中请求了 rolesgroups 声明,请验证用户是否在允许执行此操作的组中。If you've requested the roles or groups claims in the access token, verify that the user is in the group allowed to do this action.
    • 对于使用隐式流检索的令牌,可能需要在 Microsoft Graph 中查询此数据,因为该数据通常很庞大,无法放到令牌中。For tokens retrieved using the implicit flow, you'll likely need to query the Microsoft Graph for this data, as it's often too large to fit in the token.

用户和应用程序令牌User and application tokens

应用程序可以代表用户接收令牌(常用的流),或者直接从应用程序接收令牌(通过客户端凭据流)。Your application may receive tokens on behalf of a user (the usual flow) or directly from an application (through the client credentials flow). 这些仅限应用的令牌表示这种调用来自应用程序,而没有支持它的用户。These app-only tokens indicate that this call is coming from an application and does not have a user backing it. 这些令牌的处理方式大致相同,但存在一些差别:These tokens are handled largely the same, with some differences:

  • 仅限应用的令牌不包含 scp 声明,而是包含 roles 声明。App-only tokens will not have a scp claim, and may instead have a roles claim. 这是记录应用程序权限的位置(与委托的权限相反)。This is where application permission (as opposed to delegated permissions) will be recorded. 有关委托的权限和应用程序权限的详细信息,请参阅 v1.0v2.0 中的权限与许可。For more information about delegated and application permissions, see permission and consent in v1.0 and v2.0.
  • 许多特定于用户的声明将会缺失,例如 nameupnMany human-specific claims will be missing, such as name or upn.
  • suboid 声明相同。The sub and oid claims will be the same.

令牌吊销Token revocation

刷新令牌可能由于不同的原因而随时失效或吊销。Refresh tokens can be invalidated or revoked at any time, for different reasons. 这些原因主要分为两个类别:超时和吊销。These fall into two main categories: timeouts and revocations.

令牌超时Token timeouts

  • MaxInactiveTime:如果在 MaxInactiveTime 指定的时间内未使用刷新令牌,刷新令牌将不再有效。MaxInactiveTime: If the refresh token hasn't been used within the time dictated by the MaxInactiveTime, the Refresh Token will no longer be valid.
  • MaxSessionAge:如果 MaxAgeSessionMultiFactor 或 MaxAgeSessionSingleFactor 已设置为其默认值(“直到吊销”)以外的值,则在经过 MaxAgeSession* 中设置的时间后,需要重新进行身份验证。MaxSessionAge: If MaxAgeSessionMultiFactor or MaxAgeSessionSingleFactor have been set to something other than their default (Until-revoked), then reauthentication will be required after the time set in the MaxAgeSession* elapses.
  • 示例:Examples:
    • 租户的 MaxInactiveTime 为 5 天,用户去度假一周,因此 Azure AD 在 7 天内未看到用户发出的新令牌请求。The tenant has a MaxInactiveTime of five days, and the user went on vacation for a week, and so Azure AD hasn't seen a new token request from the user in 7 days. 下次用户请求新令牌时,他们将看到其刷新令牌已被吊销,他们必须重新输入其凭据。The next time the user requests a new token, they'll find their Refresh Token has been revoked, and they must enter their credentials again.
    • 敏感应用程序的 MaxAgeSessionSingleFactor 为 1 天。A sensitive application has a MaxAgeSessionSingleFactor of one day. 如果用户在星期一登录,则在星期二(25 个小时后),他们需要重新进行身份验证。If a user logs in on Monday, and on Tuesday (after 25 hours have elapsed), they'll be required to reauthenticate.

撤销Revocation

基于密码的 CookiePassword-based cookie 基于密码的令牌Password-based token 不基于密码的 CookieNon-password-based cookie 不基于密码的令牌Non-password-based token 机密客户端令牌Confidential client token
密码过期Password expires 一直有效Stays alive 一直有效Stays alive 一直有效Stays alive 一直有效Stays alive 一直有效Stays alive
用户更改了密码Password changed by user 已撤销Revoked 已撤销Revoked 一直有效Stays alive 一直有效Stays alive 一直有效Stays alive
用户执行 SSPRUser does SSPR 已撤销Revoked 已撤销Revoked 一直有效Stays alive 一直有效Stays alive 一直有效Stays alive
管理员重置密码Admin resets password 已撤销Revoked 已撤销Revoked 一直有效Stays alive 一直有效Stays alive 一直有效Stays alive
用户通过 PowerShell 撤销刷新令牌User revokes their refresh tokens via PowerShell 已撤销Revoked 已撤销Revoked 已撤销Revoked 已撤销Revoked 已撤销Revoked
管理员通过 PowerShell 撤销租户的所有刷新令牌Admin revokes all refresh tokens for the tenant via PowerShell 已撤销Revoked 已撤销Revoked 已撤销Revoked 已撤销Revoked 已撤销Revoked
在 Web 上单一登录Single sign-out on web 已撤销Revoked 一直有效Stays alive 已撤销Revoked 一直有效Stays alive 一直有效Stays alive

Note

“不基于密码”登录是指用户在未键入密码的情况下登录。A "Non-password based" login is one where the user didn't type in a password to get it. 例如,在 Windows Hello 中进行人脸登录、使用 FIDO 密钥或 PIN 登录。For example, using your face with Windows Hello, a FIDO key, or a PIN.

Windows 主刷新令牌存在已知问题。A known issue exists with the Windows Primary Refresh Token. 如果 PRT 是通过密码获取,然后用户通过 Hello 登录,这不会更改 PRT 的来源,并且它会在用户更改密码时遭撤销。If the PRT is obtained via a password, and then the user logs in via Hello, this does not change the origination of the PRT, and it will be revoked if the user changes their password.

在用于提取新访问令牌和刷新令牌时,刷新令牌不会失效或撤销。Refresh tokens aren't invalidated or revoked when used to fetch a new access token and refresh token.

后续步骤Next steps