Microsoft 标识平台 ID 令牌Microsoft identity platform ID tokens

id_tokens 是在 OpenID Connect 流中发送到客户端应用程序的。id_tokens are sent to the client application as part of an OpenID Connect flow. 它们可以一起发送来代替访问令牌,可供客户端用来对用户进行身份验证。They can be sent along side or instead of an access token, and are used by the client to authenticate the user.

使用 id_tokenUsing the id_token

ID 令牌应该用来验证某个用户是否符合其声称的身份,以及用来获取该用户的其他有用信息 - 它不应该用来替代访问令牌进行授权。ID Tokens should be used to validate that a user is who they claim to be and get additional useful information about them - it shouldn't be used for authorization in place of an access token. 它提供的声明可以用于应用程序内部的用户体验、作为数据库中的键以及提供客户端应用程序访问权限。The claims it provides can be used for UX inside your application, as keys in a database, and providing access to the client application. 为数据库创建键时,不应使用 idp,因为它会扰乱来宾方案。When creating keys for a database, idp should not be used because it messes up guest scenarios. 应当仅在 sub 上进行键控(这始终是唯一的),如果需要,可以使用 tid 进行路由。Keying should be done on sub alone (which is always unique), with tid used for routing if need be. 如果需要跨服务共享数据,oid+sub+tid 将起作用,因为多个服务都获得相同的 oidIf you need to share data across services, oid+sub+tid will work since multiple services all get the same oid.

id_token 中的声明Claims in an id_token

Microsoft 标识的 id_tokensJWT,这意味着它们由标头、有效负载和签名部分组成。id_tokens for a Microsoft identity are JWTs, meaning they consist of a header, payload, and signature portion. 可以使用标头和签名来验证令牌的真实性,而有效负载则包含客户端请求的用户信息。You can use the header and signature to verify the authenticity of the token, while the payload contains the information about the user requested by your client. 除非另有说明,否则此处列出的所有声明均出现在 v1.0 和 v2.0 令牌中。Except where noted, all claims listed here appear in both v1.0 and v2.0 tokens.

v1.0v1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyIsImtpZCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyJ9.eyJhdWQiOiJiMTRhNzUwNS05NmU5LTQ5MjctOTFlOC0wNjAxZDBmYzljYWEiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkvIiwiaWF0IjoxNTM2Mjc1MTI0LCJuYmYiOjE1MzYyNzUxMjQsImV4cCI6MTUzNjI3OTAyNCwiYWlvIjoiQVhRQWkvOElBQUFBcXhzdUIrUjREMnJGUXFPRVRPNFlkWGJMRDlrWjh4ZlhhZGVBTTBRMk5rTlQ1aXpmZzN1d2JXU1hodVNTajZVVDVoeTJENldxQXBCNWpLQTZaZ1o5ay9TVTI3dVY5Y2V0WGZMT3RwTnR0Z2s1RGNCdGsrTExzdHovSmcrZ1lSbXY5YlVVNFhscGhUYzZDODZKbWoxRkN3PT0iLCJhbXIiOlsicnNhIl0sImVtYWlsIjoiYWJlbGlAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiTGluY29sbiIsImdpdmVuX25hbWUiOiJBYmUiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaXBhZGRyIjoiMTMxLjEwNy4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJub25jZSI6IjEyMzUyMyIsIm9pZCI6IjA1ODMzYjZiLWFhMWQtNDJkNC05ZWMwLTFiMmJiOTE5NDQzOCIsInJoIjoiSSIsInN1YiI6IjVfSjlyU3NzOC1qdnRfSWN1NnVlUk5MOHhYYjhMRjRGc2dfS29vQzJSSlEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6IkFiZUxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJMeGVfNDZHcVRrT3BHU2ZUbG40RUFBIiwidmVyIjoiMS4wIn0=.UJQrCA6qn2bXq57qzGX_-D3HcPHqBMOKDPx4su1yKRLNErVD8xkxJLNLVRdASHqEcpyDctbdHccu6DPpkq5f0ibcaQFhejQNcABidJCTz0Bb2AbdUCTqAzdt9pdgQvMBnVH1xk3SCM6d4BbT4BkLLj10ZLasX7vRknaSjE_C5DI7Fg4WrZPwOhII1dB0HEZ_qpNaYXEiy-o94UJ94zCr07GgrqMsfYQqFR7kn-mn68AjvLcgwSfZvyR_yIK75S_K37vC3QryQ7cNoafDe9upql_6pB2ybMVlgWPs_DmbJ8g0om-sPlwyn74Cc1tW3ze-Xptw_2uVdPgWyqfuWAfq6Q

jwt.ms 中查看此 v1.0 示例令牌。View this v1.0 sample token in jwt.ms.

v2.0v2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjFMVE16YWtpaGlSbGFfOHoyQkVKVlhlV01xbyJ9.eyJ2ZXIiOiIyLjAiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vOTEyMjA0MGQtNmM2Ny00YzViLWIxMTItMzZhMzA0YjY2ZGFkL3YyLjAiLCJzdWIiOiJBQUFBQUFBQUFBQUFBQUFBQUFBQUFJa3pxRlZyU2FTYUZIeTc4MmJidGFRIiwiYXVkIjoiNmNiMDQwMTgtYTNmNS00NmE3LWI5OTUtOTQwYzc4ZjVhZWYzIiwiZXhwIjoxNTM2MzYxNDExLCJpYXQiOjE1MzYyNzQ3MTEsIm5iZiI6MTUzNjI3NDcxMSwibmFtZSI6IkFiZSBMaW5jb2xuIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiQWJlTGlAbWljcm9zb2Z0LmNvbSIsIm9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC02NmYzLTMzMzJlY2E3ZWE4MSIsInRpZCI6IjkxMjIwNDBkLTZjNjctNGM1Yi1iMTEyLTM2YTMwNGI2NmRhZCIsIm5vbmNlIjoiMTIzNTIzIiwiYWlvIjoiRGYyVVZYTDFpeCFsTUNXTVNPSkJjRmF0emNHZnZGR2hqS3Y4cTVnMHg3MzJkUjVNQjVCaXN2R1FPN1lXQnlqZDhpUURMcSFlR2JJRGFreXA1bW5PcmNkcUhlWVNubHRlcFFtUnA2QUlaOGpZIn0.1AFWW-Ck5nROwSlltm7GzZvDwUkqvhSQpm55TQsmVo9Y59cLhRXpvB8n-55HCr9Z6G_31_UbeUkoz612I2j_Sm9FFShSDDjoaLQr54CreGIJvjtmS3EkK9a7SJBbcpL1MpUtlfygow39tFjY7EVNW9plWUvRrTgVk7lYLprvfzw-CIqw3gHC-T7IK_m_xkr08INERBtaecwhTeN4chPC4W3jdmw_lIxzC48YoQ0dB1L9-ImX98Egypfrlbm0IBL5spFzL6JDZIRRJOu8vecJvj1mq-IUhGt0MacxX8jdxYLP-KUu2d9MbNKpCKJuZ7p8gwTL5B7NlUdh_dmSviPWrw

jwt.ms 中查看此 v2.0 示例令牌。View this v2.0 sample token in jwt.ms.

标头声明Header claims

声明Claim 格式Format 说明Description
typ 字符串 - 始终为“JWT”String - always "JWT" 指示令牌是 JWT。Indicates that the token is a JWT.
alg StringString 指示用于对令牌签名的算法。Indicates the algorithm that was used to sign the token. 示例:“RS256”Example: "RS256"
kid StringString 用于对此令牌进行签名的公钥的指纹。Thumbprint for the public key used to sign this token. 已在 v1.0 和 v2.0 id_tokens 中发出。Emitted in both v1.0 and v2.0 id_tokens.
x5t StringString kid 相同(在用法和值方面)。The same (in use and value) as kid. 但是,这是在 v1.0 id_tokens 中仅出于兼容目的而发出的旧式声明。However, this is a legacy claim emitted only in v1.0 id_tokens for compatibility purposes.

有效负载声明Payload claims

此列表显示了默认情况下位于 most id_tokens 中的声明(另外说明的除外)。This list shows the claims that are in most id_tokens by default (except where noted). 但是,应用可以使用可选声明来请求 id_token 中的其他声明。However, your app can use optional claims to request additional claims in the id_token. 这些声明的范围可以从 groups 声明到有关用户名称的信息。These can range from the groups claim to information about the user's name.

声明Claim 格式Format 说明Description
aud 字符串,应用 ID URIString, an App ID URI 标识令牌的目标接收方。Identifies the intended recipient of the token. id_tokens 中,受众是在 Azure 门户中分配给应用的应用程序 ID。In id_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 终结点颁发,则 URI 将以 /v2.0 结尾。If the token was issued by the v2.0 endpoint, 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.
iat int,UNIX 时间戳int, a UNIX timestamp “Issued At”表示针对此令牌进行身份验证的时间。"Issued At" indicates when the authentication for this token occurred.
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.
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 - if, for example, a change in authentication is required or a token revocation has been detected.
c_hash StringString 仅当 ID 令牌随 OAuth 2.0 授权代码一起颁发时,代码哈希才包含在 ID 令牌中。The code hash is included in ID tokens only when the ID token is issued with an OAuth 2.0 authorization code. 它可用于验证授权代码的真实性。It can be used to validate the authenticity of an authorization code. 有关执行此验证的详细信息,请参阅 OpenID Connect 规范For details about performing this validation, see the OpenID Connect specification.
at_hash StringString 仅当 ID 令牌随 OAuth 2.0 访问令牌一起颁发时,访问令牌哈希才包含在 ID 令牌中。The access token hash is included in ID tokens only when the ID token is issued with an OAuth 2.0 access token. 它可用于验证访问令牌的真实性。It can be used to validate the authenticity of an access token. 有关执行此验证的详细信息,请参阅 OpenID Connect 规范For details about performing this validation, see the OpenID Connect specification.
aio 不透明字符串Opaque String 一个内部声明,Azure AD 用它来记录有关重复使用令牌的数据。An internal claim used by Azure AD to record data for token reuse. 应忽略。Should be ignored.
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. 需要 profile 范围才能接收此声明。The profile scope is required to receive this claim.
email StringString 对于具有电子邮件地址的来宾帐户,默认情况下会提供 email 声明。The email claim is present by default for guest accounts that have an email address. 你的应用可以使用 email 可选声明为托管用户(来自与资源相同的租户)请求电子邮件声明。Your app can request the email claim for managed users (those from the same tenant as the resource) using the email optional claim. 在 v2.0 终结点上,应用程序还可以请求 email OpenID Connect 范围 - 你无需同时请求可选声明和范围来获取声明。On the v2.0 endpoint, your app can also request the email OpenID Connect scope - you don't need to request both the optional claim and the scope to get the claim. 电子邮件声明仅支持来自用户个人资料信息的可寻址邮件。The email claim only supports addressable mail from the user's profile information.
name StringString name 声明提供了标识令牌使用者的用户可读值。The name claim provides a human-readable value that identifies the subject of the token. 该值不一定唯一,而且可变,只能用于显示目的。The value isn't guaranteed to be unique, it is mutable, and it's designed to be used only for display purposes. 需要 profile 作用域才能接收此声明。The profile scope is required to receive this claim.
nonce StringString nonce 与发送给 IDP 的原始 /authorize 请求中包含的参数匹配。The nonce matches the parameter included in the original /authorize request to the IDP. 如果不匹配,应用程序会拒绝此令牌。If it does not match, your application should reject the token.
oid 字符串,GUIDString, a GUID 在 Microsoft 标识系统中,对象的不可变标识符在这种情况下是用户帐户。The immutable identifier for an object in the Microsoft identity system, in this case, a user account. 此 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 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 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're considered different accounts, even though the user logs into each account with the same credentials. oid 声明是一个 GUID,不能重复使用。The oid claim is a GUID and cannot be reused.
roles 字符串数组Array of strings 分配给已登录用户的角色集。The set of roles that were assigned to the user who is logging in.
rh 不透明字符串Opaque String Azure 用来重新验证令牌的内部声明。An internal claim used by Azure to revalidate tokens. 应忽略。Should be ignored.
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. 使用者是成对标识符 - 它对特定应用程序 ID 是唯一的。The subject is a pairwise identifier - it is unique to a particular application ID. 如果单个用户使用两个不同的客户端 ID 登录到两个不同的应用,这些应用将收到两个不同的使用者声明值。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 wanted depending on your architecture and privacy requirements.
tid 字符串,GUIDString, a GUID 表示用户所属的 Azure AD 租户的 GUID。A GUID that 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 to receive this claim.
unique_name StringString 提供一个用户可读值,用于标识令牌使用者。Provides a human readable value that identifies the subject of the token. 此值在任何给定时间点都是唯一的,但随着电子邮件和其他标识符的重复使用,此值可能会重新出现在其他帐户上,因此只应该用于显示目的。This value is unique at any given point in time, but as emails and other identifiers can be reused, this value can reappear on other accounts, and should therefore be used only for display purposes. 仅在 v1.0 id_tokens 中颁发。Only issued in v1.0 id_tokens.
uti 不透明字符串Opaque String Azure 用来重新验证令牌的内部声明。An internal claim used by Azure to revalidate tokens. 应忽略。Should be ignored.
ver 字符串,1.0 或 2.0String, either 1.0 or 2.0 指示 id_token 的版本。Indicates the version of the id_token.

Note

v1 和 v2 id_token 携带的信息量存在差异,如上述示例所示。The v1 and v2 id_token have differences in the amount of information they will carry as seen from the examples above. 该版本实质上指定了从其颁发它的 Azure AD 平台终结点。The version essentially specifies the Azure AD platform endpoint from where it was issued. Azure AD Oauth 实现多年来一直在发展。Azure AD Oauth implementation have evolved through the years. 目前,我们有两个不同的用于 AzureAD 应用程序的 oAuth 终结点。Currently we have two different oAuth endpoints for AzureAD applications. 可以使用归类为 v2 的任何新终结点,也可以使用称为 v1 的旧终结点。You can use any of the new endpoints which are categorized as v2 or the old one which is said to be v1. 这两个终结点的 Oauth 终结点是不同的。The Oauth endpoints for both of them are different. V2 终结点是更新的终结点,我们尝试在其中迁移 v1 终结点的所有功能。建议新开发人员使用 v2 终结点。The V2 endpoint is the newer one where we are trying to migrate all the features of v1 endpoint and recommend new developers to use the v2 endpoint.

  • V1:Azure Active Directory 终结点:https://login.partner.microsoftonline.cn/common/oauth2/authorizeV1: Azure Active Directory Endpoints: https://login.partner.microsoftonline.cn/common/oauth2/authorize
  • V2:Microsoft 标识平台终结点:https://login.partner.microsoftonline.cn/common/oauth2/v2.0/authorizeV2: Microsoft Identity Platform Endpoints: https://login.partner.microsoftonline.cn/common/oauth2/v2.0/authorize

验证 id_tokenValidating an id_token

验证 id_token验证访问令牌的第一步类似 - 客户端应验证是否是正确的颁发者发送回令牌且令牌未遭篡改。Validating an id_token is similar to the first step of validating an access token - your client should validate that the correct issuer has sent back the token and that it hasn't been tampered with. 由于 id_tokens 始终是 JWT,因此可以使用许多现有的库来验证这些令牌 - 建议使用这其中的一个库来验证,而不要自行进行验证。Because id_tokens are always a JWT, many libraries exist to validate these tokens - we recommend you use one of these rather than doing it yourself.

若要手动验证令牌,请参阅验证访问令牌中详述的步骤。To manually validate the token, see the steps details in validating an access token. 验证令牌上的签名以后,应验证 id_token 中的以下声明(这些也可以由令牌验证库来完成):After validating the signature on the token, the following claims should be validated in the id_token (these may also be done by your token validation library):

  • 时间戳:iatnbfexp 时间戳全都应位于当前时间之前或之后(具体取决于需要)。Timestamps: the iat, nbf, and exp timestamps should all fall before or after the current time, as appropriate.
  • 受众:aud 声明应该与应用程序的应用 ID 匹配。Audience: the aud claim should match the app ID for your application.
  • Nonce:有效负载中的 nonce 声明必须与进行初始请求时传递到 /authorize 终结点中的 nonce 参数匹配。Nonce: the nonce claim in the payload must match the nonce parameter passed into the /authorize endpoint during the initial request.

后续步骤Next steps