識別碼權杖宣告參考

識別碼權杖是 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 。 GUID，指出使用者是來自 Microsoft 帳戶的取用者使用者。 9188040d-6c67-4c5b-b112-36a304b66dad 您的應用程式應該使用宣告的 GUID 部分來限制一組可登入應用程式的租使用者，如果適用的話。
iat	int，Unix 時間戳記	指出權杖的驗證何時發生。
idp	字串，通常是 STS URI	記錄已驗證權杖主體的識別提供者。 此值與簽發者宣告的值相同，除非使用者帳戶不在與簽發者相同的租使用者中 ， 例如來賓。 如果宣告不存在，表示 可以改用 的值 iss 。 針對在組織內容中使用的個人帳戶（例如，受邀加入租使用者的個人帳戶）， idp 宣告可能是 「live.com」或包含 Microsoft 帳戶租 9188040d-6c67-4c5b-b112-36a304b66dad 使用者的 STS URI。
nbf	int，Unix 時間戳記	識別無法接受 JWT 進行處理的時間。
exp	int，Unix 時間戳記	識別無法接受 JWT 進行處理的到期時間。 在某些情況下，資源可能會在此時間之前拒絕權杖。 例如，如果需要驗證變更，或偵測到權杖撤銷。
c_hash	String	只有在使用 OAuth 2.0 授權碼發出識別碼權杖時，才會將程式碼雜湊包含在識別碼權杖中。 它可用來驗證授權碼的真實性。 若要瞭解如何進行這項驗證，請參閱 OpenID 連線規格 。 此宣告不會在 /token 端點的識別碼權杖上傳回。
at_hash	String	只有當識別碼權杖從具有 OAuth 2.0 存取權杖的 /authorize 端點發出識別碼權杖時，存取權杖雜湊才會包含在識別碼權杖中。 它可以用來驗證存取權杖的真實性。 若要瞭解如何進行這項驗證，請參閱 OpenID 連線規格 。 此宣告不會在端點的 /token 識別碼權杖上傳回。
aio	不透明字串	用來記錄資料以供重複使用權杖的內部宣告。 應該忽略。
preferred_username	String	代表使用者的主要使用者名稱。 它可以是電子郵件地址、電話號碼，或沒有指定格式的一般使用者名稱。 其值是可變的，而且可能會隨著時間而變更。 由於它是可變動的，所以此值無法用來做出授權決策。 它可用於使用者名稱提示和人類可讀取 UI 中作為使用者名稱。 需要 profile 範圍才能接收此宣告。 僅存在於 v2.0 權杖中。
email	String	根據預設，針對具有電子郵件地址的來賓帳戶顯示 。 您的應用程式可以使用選擇性宣告，向受控使用者要求電子郵件宣告 （與資源 email 相同的租使用者）。 此值不保證正確，而且會隨著時間變動。 請勿將它用於授權或儲存使用者的資料。 如果您需要應用程式中的可定址電子郵件地址，請使用此宣告作為建議或預先填入 UX，直接從使用者要求此資料。 在 v2.0 端點上，您的應用程式也可以要求 OpenID 連線 範圍 - 您不需要要求 email 選擇性宣告和範圍來取得宣告。
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 for Life 或 Outlook 等服務），此值為 9188040d-6c67-4c5b-b112-36a304b66dad 。
unique_name	String	僅存在於 v1.0 權杖中。 提供人類可讀取的值，以識別權杖的主體。 此值不保證在租使用者內是唯一的，而且應該僅用於顯示用途。
uti	String	權杖識別碼宣告，相當於 jti JWT 規格中的 。 區分大小寫的唯一個別權杖識別碼。
ver	字串，可以是 1.0 或 2.0	指出識別碼權杖的版本。
hasgroups	布林值	如果存在，一律為 true，表示使用者至少在一個群組中。 當完整群組宣告將 URI 片段延伸超過 URL 長度限制（目前為六個以上群組）時，用來取代隱含授與流程中 JWT 的群組宣告。 指出用戶端應該使用 Microsoft Graph API 來判斷使用者的群組 （ https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects ）。
groups:src1	JSON 物件	對於長度不受限但對權杖而言 hasgroups 仍然太大的權杖要求，則會包含使用者的完整群組清單連結。 針對 JWT 做為分散式宣告，針對 SAML 作為取代宣告的新宣告 groups 。 範例 JWT 值 ： "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" } 如需詳細資訊，請參閱 群組超額宣告 。

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

識別使用者時，請務必使用一段時間保持不變且唯一的資訊。 繼承應用程式有時會使用電子郵件地址、電話號碼或 UPN 等欄位。 所有這些欄位都可以隨著時間而變更，也可以隨著時間重複使用。 例如，當員工變更其名稱，或員工獲得符合先前的電子郵件地址時，不再存在員工。 您的應用程式不得使用人類可讀取的資料來識別使用者 - 人類可讀取通常表示有人可以讀取它，並想要變更它。 請改用 OIDC 標準所提供的宣告，或 Microsoft 提供的擴充宣告 - sub 和 oid 宣告。

若要正確儲存每位使用者的資訊，請使用或 oid 單獨使用或單獨使用 sub GUID，並 tid 視需要用於路由或分區化。 如果您需要跨服務共用資料， oid 而且 tid 最好是所有應用程式都取得相同 oid 且 tid 在租使用者中運作的使用者宣告。 宣告 sub 是唯一的成對值。 此值是以權杖收件者、租使用者和使用者的組合為基礎。 要求使用者識別碼權杖的兩個應用程式會收到不同的 sub 宣告，但該使用者的宣告相同 oid 。

注意

請勿使用 idp 宣告來儲存使用者的相關資訊，以嘗試將租使用者之間的使用者相互關聯。 它無法運作，因為 oidsub 和宣告使用者會依設計在租使用者之間變更，以確保應用程式無法跨租使用者追蹤使用者。

來賓案例，其中使用者位於一個租使用者中，並在另一個租使用者中驗證，應該將使用者視為服務的新使用者。 一個租使用者中的檔和許可權不應套用在另一個租使用者中。 這項限制對於防止跨租使用者意外的資料外泄，以及強制執行資料生命週期非常重要。 從租使用者收回來賓也應該移除其存取該租使用者中建立的資料。

群組超額宣告

為了確保權杖大小未超過 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 中使用的識別碼權杖。