Microsoft 身分識別平臺識別碼權杖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 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. 它所提供的宣告可用於應用程式內的 UX、做為資料庫中的索引鍵,以及提供用戶端應用程式的存取權。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 單獨完成(這一律是唯一的),並在需要時用於路由的 tidKeying 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

此清單會顯示預設為最 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 字串,應用程式識別碼 URIString, an App ID URI 識別權杖的預定接收者。Identifies the intended recipient of the token. id_tokens 中,對象是在 Azure 入口網站中指派給應用程式的應用程式識別碼。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 識別建構並傳回權杖的 Security Token Service (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.0If the token was issued by the v2.0 endpoint, the URI will end in /v2.0. 指出使用者是來自 Microsoft 帳戶之取用者使用者的 GUID 是 9188040d-6c67-4c5b-b112-36a304b66dadThe GUID that indicates that the user is a consumer user from a Microsoft account is 9188040d-6c67-4c5b-b112-36a304b66dad. 您的應用程式應該使用宣告的 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 整數,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. 針對在組織內容中使用的個人帳戶 (例如獲邀使用 Azure AD 租用戶的個人帳戶),idp 宣告可能會是 'live.com' 或包含 Microsoft 帳戶租用戶 9188040d-6c67-4c5b-b112-36a304b66dad 的 STS URI。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.
nbf 整數,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 整數,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 只有當識別碼權杖是隨著 OAuth 2.0 授權碼一起簽發時,代碼雜湊才會包含在識別碼權杖中。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 只有當識別碼權杖是隨著 OAuth 2.0 存取權杖一起簽發時,存取權杖雜湊才會包含在識別碼權杖中。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. 此識別碼可跨應用程式唯一識別使用者,同一位使用者登入兩個不同的應用程式會在 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 屬性。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. 請注意,如果單一使用者存在於多個租使用者中,使用者將會在每個租使用者中包含不同的物件識別碼-它們會被視為不同的帳戶,即使使用者使用相同的認證登入每個帳戶也是一樣。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. @No__t_0 宣告是 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. 主體是成對識別碼,對於特定應用程式識別碼來說,主體是唯一的。The subject is a pairwise identifier - it is unique to a particular application 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 是使用者所屬組織的不可變租用戶識別碼。For work and school accounts, the GUID is the immutable tenant ID of the organization that the user belongs to. 就個人帳戶而言,此值會是 9188040d-6c67-4c5b-b112-36a304b66dadFor personal accounts, the value is 9188040d-6c67-4c5b-b112-36a304b66dad. 需要 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 isn't guaranteed to be unique within a tenant and should 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.

驗證 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):

  • 時間戳記:iat``nbfexp 時間戳記應該全部落在目前時間的前後 (視情況而定)。Timestamps: the iat, nbf, and exp timestamps should all fall before or after the current time, as appropriate.
  • 對象:aud 宣告應符合您應用程式的應用程式識別碼。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