識別碼權杖宣告參考

文章
06/28/2024

識別碼權杖是 JSON Web 權杖 (JWT)。 v1.0 和 v2.0 識別碼權杖中所攜帶的資訊有差異。版本是取決於要求所在的端點。雖然現有的應用程式可能會使用 Azure AD v1.0 端點，但新的應用程式應該使用 v2.0 端點。

v1.0：https://login.microsoftonline.com/common/oauth2/authorize
v2.0：https://login.microsoftonline.com/common/oauth2/v2.0/authorize

除非另外註記，否則下列章節中列出的所有 JWT 宣告都會顯示在 v1.0 和 v2.0 權杖中。識別碼權杖包含標頭、承載和簽章。標頭和簽章會用於驗證權杖的真確性，而承載則包含您用戶端所要求使用者的相關資訊。

標頭宣告

下表顯示識別碼權杖中存在的標頭宣告。

索賠	格式	描述
`typ`	字串 - 一律為 "JWT"	表示權杖是 JWT 權杖。
`alg`	String	指出用來簽署權杖的演算法。範例："RS256"
`kid`	String	指定公開金鑰的指紋，可用來驗證此權杖的簽章。 v1.0 和 v2.0 識別碼權杖中都會發出此宣告。
`x5t`	String	與 `kid` 的功能一樣 (用法和值)。 `x5t` 是只在 v1.0 識別碼權杖中發出的舊版宣告，僅針對相容性使用。

承載宣告

下表顯示預設情況下大多數識別碼權杖的宣告 (除非註記)。不過，您的應用程式可以使用選擇性宣告來要求識別碼權杖中的多個宣告。選擇性宣告的範圍可以從 groups 宣告到使用者名稱的相關資訊。

索賠	格式	描述
`aud`	字串，應用程式識別碼 GUID	識別權杖的預定接收者。在 `id_tokens` 中，對象是在 Azure 入口網站中指派給應用程式的應用程式識別碼。此值應經過驗證。如果權杖不符合您應用程式的應用程式識別碼，則應該拒絕權杖。
`iss`	字串，簽發者 URI	識別簽發者，或是建構和傳回權杖的「授權伺服器」。這也會識別用於驗證使用者的租用戶。如果是由 v2.0 端點發出的權杖，則 URI 會以 `/v2.0` 結尾。指出使用者是來自 Microsoft 帳戶之取用者使用者的 GUID 是 `9188040d-6c67-4c5b-b112-36a304b66dad`。您的應用程式應該使用宣告的 GUID 部分來限制可登入應用程式的租用戶集合 (如果有的話)。
`iat`	整數，Unix 時間戳記	指出權杖進行驗證的時間。
`idp`	字串，通常是 STS URI	記錄驗證權杖主體的身分識別提供者。除非使用者帳戶與簽發者不在同一租用戶中，否則此值與簽發者宣告的值相同。如果宣告不存在，這代表可改用 `iss` 的值。若為組織內容中所使用的個人帳戶 (例如，獲邀使用租用戶的個人帳戶)，`idp` 宣告可能是 'live.com' 或包含 Microsoft 帳戶租用戶 `9188040d-6c67-4c5b-b112-36a304b66dad` 的 STS URI。
`nbf`	整數，Unix 時間戳記	識別時間，在此時間之前不可接受 JWT 以進行處理。
`exp`	整數，Unix 時間戳記	識別到期時間，在此時間或之後不得接受 JWT 並進行處理。在某些情況下，在此時間之前，資源可能會拒絕權杖。例如，如果驗證需要變更或偵測到權杖撤銷。
`c_hash`	String	只有當識別碼權杖是隨著 OAuth 2.0 授權碼一起簽發時，代碼雜湊才會包含在識別碼權杖中。它可用來驗證授權碼的真實性。若要了解如何進行這種驗證，請參閱 OpenID Connect 規格。對於來自 /token 端點的識別碼權杖，不會傳回此宣告。
`at_hash`	String	只有當識別碼權杖是簽發自具有 OAuth 2.0 存取權杖的 `/authorize` 端點時，存取權杖雜湊才會包含在識別碼權杖中。它可用來驗證存取權杖的真實性。若要了解如何進行這種驗證，請參閱 OpenID Connect 規格。對於來自 `/token` 端點的識別碼權杖，不會傳回此宣告。
`aio`	不透明字串	用來記錄資料以便重複使用權杖的內部宣告。應該予以忽略。
`preferred_username`	String	代表使用者的主要使用者名稱。它可以是電子郵件地址、電話號碼或未指定格式的一般使用者名稱。其值是可變動的，並且可能隨著時間改變。因為此值會變動，請勿用於授權決策。此值可用於使用者名稱提示，並在人類看得懂的 UI 中做為使用者名稱。接收此宣告需要 `profile` 範圍。只出現在 v2.0 權杖中。
`email`	String	依預設會顯示給擁有電子郵件地址的來賓帳戶。您的應用程式可以使用選擇性宣告，向受控使用者要求電子郵件宣告（與資源`email`相同的租使用者）。此值不保證正確，而且會隨著時間變動。請勿將其用於授權或用來儲存使用者的資料。若應用程式需要可定址的電子郵件地址，請使用此宣告作為建議或預先填入您的 UX，直接向使用者要求此資料。在 v2.0 端點上，應用程式也可以要求 `email` OpenID Connect 範圍 - 您不需要同時要求選擇性宣告和用來取得宣告的範圍。
`name`	String	`name` 宣告會提供人類看得懂的值，用以識別權杖的主體。此值不保證是唯一值，可進行變更，且應僅用於顯示目的。接收此宣告需要 `profile` 範圍。
`nonce`	String	Nonce 符合對 IDP 的原始授權要求中包含的參數。如果不符，您的應用程式應該拒絕權杖。
`oid`	字串，GUID	物件的不可變識別碼，在此案例中為使用者帳戶。此識別碼可跨應用程式唯一識別使用者 - 同一位使用者登入兩個不同的應用程式會在 `oid` 宣告中收到相同的值。 Microsoft Graph 會傳回此識別碼作為使用者帳戶的 `id` 屬性。因為 `oid` 可讓多個應用程式相互關聯使用者，因此需要 `profile` 範圍才能接收此宣告。如果單一使用者存在於多個租用戶，使用者會在每個租用戶中包含不同的物件識別碼 - 即使使用者使用相同的認證來登入各個帳戶，仍會被視為不同帳戶。 `oid` 宣告是 GUID 且無法重複使用。
`roles`	字串陣列	指派給登入使用者的一組角色。
`rh`	不透明字串	用來重新驗證權杖的內部宣告。應該予以忽略。
`sub`	String	權杖中資訊的主體。例如，應用程式的使用者。這個值不可變，而且無法重新指派或重複使用。主體是配對識別碼，而且對應用程式識別碼而言是唯一的。如果單一使用者使用兩個不同的用戶端識別碼登入兩個不同的應用程式，這些應用程式會收到兩個不同的主體宣告值。視您的架構和隱私權需求而定，您不一定想要兩個值。
`tid`	字串，GUID	代表使用者要登入的租用戶。就工作和學校帳戶而言，GUID 是使用者登入組織的不可變租用戶識別碼。若要登入個人 Microsoft 帳戶租使用者服務 (例如 Xbox、Teams Life 或 Outlook)，值為 `9188040d-6c67-4c5b-b112-36a304b66dad`。
`unique_name`	String	只存在於 v1.0 權杖中。提供人類看得懂的值，用以識別權杖的主體。此值不保證是租用戶中的唯一值，並且應該僅用於顯示目的。
`uti`	String	權杖識別碼宣告，相當於 JWT 規格中的 `jti`。區分大小寫的唯一專屬權杖識別碼。
`ver`	字串，1.0 或 2.0	表示識別碼權杖的版本。
`hasgroups`	布林值	如果有的話，一律為 true，表示使用者在至少一個群組中。若完整的群組宣告將 URI 片段延伸至超出 URL 長度限制 (目前為 6 個或以上群組)，用於在隱含授與流程中取代 JWT 的群組宣告。表示用戶端應該使用 Microsoft Graph API 來判斷使用者的群組 (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`)。
`groups:src1`	JSON 物件	若未限制長度 (請參閱 `hasgroups`) 但對權杖而言仍然太大的權杖要求，會包含使用者的完整群組清單連結。在 JWT 中以分散式宣告形式取代 `groups` 宣告，在 SAML 中則以新宣告形式取代。範例 JWT 值： `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` 如需詳細資訊，請參閱群組超額宣告。

使用宣告可以可靠地識別使用者

識別使用者時，請務必使用有一段時間保持不變且唯一的資訊。舊版應用程式有時會使用電子郵件地址、電話號碼或使用者主體名稱 (UPN) 等欄位。這些欄位都可以隨著時間變動，也可以在一段時間內重複使用。例如，當員工變更其名稱，或為員工指定的電子郵件地址符合已離職的舊員工。您的應用程式不得使用人類看得懂的資料來識別使用者 - 人類看得懂通常表示某人可以讀取及加以變更。相對地，請使用 OIDC 標準所提供的宣告，或由 Microsoft 提供的擴充宣告：sub 和 oid 宣告。

若要正確儲存每位使用者的資訊，請單獨使用 sub 或 oid (因為 GUID 是唯一的)，並在需要路由或分區化時使用 tid。若要跨服務共用資料，最佳方式是 oid 和 tid，因為所有應用程式都會取得相同的 oid 和 tid 宣告，並將宣告提供給在租用戶中執行的使用者。 sub 宣告是唯一的成對值。此值是以權杖收件者、租用戶和使用者的組合為基礎。為某個使用者要求識別碼權杖的兩個應用程式會收到不同的 sub 宣告，但該使用者會收到相同的 oid 宣告。

注意

嘗試產生跨租用戶使用者的關聯時，請勿使用 idp 宣告來儲存使用者的相關資訊。這種方式無法生效，因為使用者的 oid 和 sub 宣告會隨租用戶而變更，設計上是為確保應用程式無法跨租用戶追蹤使用者。

來賓案例，使用者位於某個租用戶中，但在另一個租用戶中進行驗證，此時應將使用者視為服務的全新使用者。一個租用戶中的文件和權限不得套用至另一個租用戶中。此限制很重要，可避免發生跨租用戶的意外資料洩漏，以及強制執行資料生命週期。從租用戶收回來賓時，也應移除其在該租用戶中所建立的資料存取權。

群組超額宣告

為確保權杖大小不會超過 HTTP 標頭大小限制，系統會限制在 groups 宣告中包含的物件識別碼數目。如果使用者所隸屬的群組數目超出超額限制 (SAML 權杖為 150，JWT 權杖為 200)，則不會在權杖納入群組宣告。相反地，其會在權杖中包含超額宣告，以指示應用程式查詢 Microsoft Graph API 來取得使用者的群組成員資格。

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

下一步

深入了解 Microsoft Entra ID 中使用的識別碼權杖。

分享方式：