存取令牌宣告參考

發行項
01/10/2024

存取令牌是 JSON Web 令牌（JWT）。 JWT 包含下列片段：

標頭 - 提供有關如何驗證令牌的資訊，包括令牌類型和其簽署方法的相關信息。
Payload - 包含嘗試呼叫服務之使用者或應用程式的所有重要數據。
簽章 - 這是用來驗證令牌的原材料。

每個片段會以句號（.）分隔，並以Base 64編碼分隔。

只有在值存在以填滿宣告時，才會存在宣告。應用程式不應該相依於存在的宣告。範例包括 pwd_exp （並非每個租使用者都需要密碼到期）和 family_name （客戶端認證流程代表沒有名稱的應用程式）。存取令牌一律會包含足夠的宣告來進行存取評估。

Microsoft 身分識別平台會使用一些宣告來協助保護令牌的重複使用。的描述 Opaque 會將這些宣告標示為不是用於公用取用。這些宣告不一定會出現在令牌中，而且可能會新增新的宣告，而不通知。

標頭宣告

索賠	格式	描述
`typ`	字串 - 一律 `JWT`	表示令牌是 JWT。
`alg`	String	表示用來簽署權杖的演算法，例如 `RS256`。
`kid`	String	指定用來驗證令牌簽章之公鑰的指紋。在 v1.0 和 v2.0 存取令牌中發出。
`x5t`	String	函式與相同（使用中與值）為 `kid`。 `x5t` 和是在 v1.0 存取令牌中針對相容性目的發出的舊版宣告。

承載宣告

索賠	格式	描述	授權考慮
`acrs`	字串的 JSON 陣列	指出持有人有資格執行之作業的驗證內容標識碼。驗證內容標識碼可用來觸發來自應用程式和服務內之逐步驗證的需求。通常與宣告一 `xms_cc` 起使用。
`aud`	字串、應用程式識別碼 URI 或 GUID	識別令牌的預期物件。在 v2.0 令牌中，此值一律是 API 的用戶端識別碼。在 v1.0 令牌中，它可以是用戶端識別碼或要求中使用的資源 URI。此值取決於用戶端要求令牌的方式。	此值必須經過驗證，如果值不符合預定物件，則拒絕令牌。
`iss`	字串，安全性令牌服務（STS） URI	識別建構及傳回令牌的 STS，以及已驗證使用者的 Microsoft Entra 租使用者。如果發行的令牌是 v2.0 令牌（請參閱 `ver` 宣告），URI 會以 `/v2.0`結尾。 GUID，指出用戶是來自 Microsoft 帳戶的取用者使用者。`9188040d-6c67-4c5b-b112-36a304b66dad`	如果適用，應用程式可以使用宣告的 GUID 部分來限制可登入應用程式的租使用者集合。
`idp`	字串，通常是 STS URI	記錄驗證權杖主體的身分識別提供者。此值與簽發者宣告的值相同，除非使用者帳戶與簽發者不在相同的租使用者中，例如來賓。如果宣告不存在，請使用的值 `iss` 。對於在組織內容中使用的個人帳戶（例如，受邀加入 Microsoft Entra 租使用者的個人帳戶）， `idp` 宣告可能是「live.com」或包含 Microsoft 帳戶租 `9188040d-6c67-4c5b-b112-36a304b66dad`使用者的 STS URI。
`iat`	int，Unix 時間戳	指定發生此權杖的驗證時間。
`nbf`	int，Unix 時間戳	指定可以處理 JWT 的時間。
`exp`	int，Unix 時間戳	指定可以接受 JWT 進行處理的到期時間。資源也可能在此時間之前拒絕令牌。驗證的必要變更或令牌被撤銷時，可能會發生拒絕。
`aio`	不透明字串	Microsoft Entra ID 用來記錄數據以供重複使用令牌的內部宣告。資源不應該使用此宣告。
`acr`	字串， `0` 或 `1`，只存在於 v1.0 令牌中	「驗證內容類別」宣告的值 `0` 表示用戶驗證不符合 ISO/IEC 29115 的需求。
`amr`	字串的 JSON 陣列，僅存在於 v1.0 令牌中	識別令牌主體的驗證方法。
`appid`	字串，GUID，僅存在於 v1.0 令牌中	使用令牌之用戶端的應用程式識別碼。應用程式可以做為本身或代表使用者。應用程式標識碼通常代表應用程式物件，但它也可以代表 Microsoft Entra ID 中的服務主體物件。	`appid` 可用於授權決策。
`azp`	字串，GUID，只存在於 v2.0 令牌中	取代 `appid` 。使用令牌之用戶端的應用程式識別碼。應用程式可以做為本身或代表使用者。應用程式標識碼通常代表應用程式物件，但它也可以代表 Microsoft Entra ID 中的服務主體物件。	`azp` 可用於授權決策。
`appidacr`	字串、、 `01`或 `2`，只存在於 v1.0 令牌中	表示客戶端的驗證方法。針對公用用戶端，值為 `0`。當您使用用戶端識別碼與客戶端密碼時，值為 `1`。當您使用客戶端憑證進行驗證時，值為 `2`。
`azpacr`	字串、、 `01`或 `2`，只存在於 v2.0 令牌中	取代 `appidacr` 。指出客戶端的驗證方法。針對公用用戶端，值為 `0`。當您使用用戶端識別碼與客戶端密碼時，值為 `1`。當您使用客戶端憑證進行驗證時，值為 `2`。
`preferred_username`	字串，只存在於 v2.0 令牌中。	代表使用者的主要用戶名稱。此值可以是電子郵件地址、電話號碼或沒有指定格式的一般用戶名稱。使用使用者名稱提示和人類可讀取UI中的值作為用戶名稱。若要接收此宣告，請使用 `profile` 範圍。	由於此值是可變的，因此請勿使用它來做出授權決策。
`name`	String	提供人類可讀取的值，以識別令牌的主體。值可能會有所不同，它是可變的，而且僅供顯示之用。若要接收此宣告，請使用 `profile` 範圍。	請勿使用此值來進行授權決策。
`scp`	字串，以空格分隔的範圍清單	用戶端應用程式已要求（且已收到）同意的應用程式所公開的範圍集合。僅包含在使用者令牌中。	應用程式應該確認這些範圍是應用程式公開的有效範圍，並根據這些範圍的值做出授權決策。
`roles`	字串數位，許可權清單	應用程式公開的許可權集，要求應用程式或使用者已獲授與呼叫許可權。用戶端認證流程會使用此許可權集來取代應用程式令牌的用戶範圍。針對使用者令牌，這個值集包含目標應用程式上使用者指派的角色。	這些值可用來管理存取權，例如強制執行存取資源的授權。
`wids`	RoleTemplateID GUID 的陣列	表示指派給此使用者的租使用者角色，從 Microsoft Entra 內建角色中的角色區段。應用程式`groupMembershipClaims`指令清單的屬性會根據每個應用程式設定此宣告。將宣告設定為 `All` 或 `DirectoryRole`。由於令牌長度考慮，可能無法出現在透過隱含流程取得的令牌中。	這些值可用來管理存取權，例如強制執行存取資源的授權。
`groups`	GUID 的 JSON 陣列	提供物件標識碼，代表主體的群組成員資格。 `groupMembershipClaims`應用程式指令清單的屬性會根據每個應用程式設定群組宣告。的值 `null` 會排除所有群組、包含目錄角色和 Active Directory 安全組成員資格的值 `SecurityGroup` ，而的值 `All` 同時包含安全組和 Microsoft 365 通訊組清單。 `hasgroups`如需搭配隱含授與使用`groups`宣告的詳細資訊，請參閱宣告。對於其他流程，如果使用者在 SAML 中超過 150 個群組數目，而 JWT 為 200 個，則 Microsoft Entra ID 會將超額宣告新增至宣告來源。宣告來源會指向包含使用者群組清單的 Microsoft Graph 端點。	這些值可用來管理存取權，例如強制執行存取資源的授權。
`hasgroups`	布林值	如果存在，則一律 `true`會指出使用者是否至少在一個群組中。 `groups`如果完整群組宣告將 URI 片段延伸超過 URL 長度限制（目前為六個以上的群組），則用來取代隱含授與流程中 JWT 的宣告。指出客戶端應該使用 Microsoft Graph API 來判斷使用者的群組（`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`）。
`groups:src1`	JSON 物件	在令牌要求對令牌而言太大時，包含使用者的完整群組清單連結。針對 JWT 做為分散式宣告，針對 SAML 作為取代宣告的新宣告 `groups` 。範例 JWT 值： `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }`
`sub`	String	與令牌相關聯的主體。例如，應用程式的使用者。此值是不可變的，請勿重新指派或重複使用。主體是特定應用程式識別碼唯一的配對標識碼。如果單一使用者使用兩個不同的用戶端標識元登入兩個不同的應用程式，則這些應用程式會收到兩個不同的主旨宣告值。使用兩個不同的值取決於架構和隱私權需求。另 `oid` 請參閱宣告，這會在租使用者內的應用程式之間維持不變。	這個值可用來執行授權檢查，例如當令牌用來存取資源時，也可以當做資料庫數據表中的密鑰使用。
`oid`	字串，GUID	要求者的不可變標識碼，這是用戶或服務主體的已驗證身分識別。此標識碼可唯一識別跨應用程式的要求者。登入相同使用者的兩個不同的應用程式會在宣告中 `oid` 收到相同的值。 `oid`當對 Microsoft 線上服務進行查詢時，可以使用，例如 Microsoft Graph。 Microsoft Graph 會傳回此標識碼作為 `id` 指定用戶帳戶的屬性。 `oid`因為允許多個應用程式將主體相互關聯，因此可接收此宣告給使用者使用`profile`範圍。如果單一使用者存在於多個租使用者中，則使用者在每個租使用者中包含不同的物件標識符。即使使用者以相同的認證登入每個帳戶，但帳戶也不同。	這個值可用來執行授權檢查，例如當令牌用來存取資源時，也可以當做資料庫數據表中的密鑰使用。
`tid`	字串，GUID	代表使用者正在登入的租使用者。針對公司與學校帳戶，GUID 是使用者登入之組織的固定租用戶標識碼。若要登入個人 Microsoft 帳戶租使用者（Xbox、Teams for Life 或 Outlook 等服務），此值為 `9188040d-6c67-4c5b-b112-36a304b66dad`。若要接收此宣告，應用程式必須要求 `profile` 範圍。	此值應該與授權決策中的其他宣告結合來考慮。
`unique_name`	字串，僅存在於 v1.0 令牌中	提供人類看得懂的值，用以識別權杖的主體。	此值在租用戶內可能不同，並只用於顯示用途。
`uti`	String	權杖識別碼宣告，相當於 `jti` JWT 規格中的。區分大小寫的唯一個別令牌標識碼。
`rh`	不透明字串	Azure 用來重新驗證令牌的內部宣告。資源不應該使用此宣告。
`ver`	字串、或`1.02.0`	指出存取令牌的版本。
`xms_cc`	字串的 JSON 陣列	指出取得令牌的用戶端應用程式是否能夠處理宣告挑戰。它通常會與宣告 `acrs`搭配使用。此宣告通常用於條件式存取和持續存取評估案例。令牌發出的資源伺服器或服務應用程式，可控制令牌中是否有此宣告。存取令牌中的值 `cp1` 是識別用戶端應用程式能夠處理宣告挑戰的權威方式。如需詳細資訊，請參閱宣告挑戰、宣告要求和用戶端功能。

群組超額宣告

Microsoft Entra ID 會限制它包含在群組宣告中的物件標識子數目，以維持在 HTTP 標頭的大小限制內。如果使用者是超過超額限制的群組成員（SAML 令牌為 150，JWT 令牌為 200，而僅使用隱含流程發出 6 個），則 Microsoft Entra ID 不會在令牌中發出群組宣告。相反地，它會在令牌中包含超額宣告，指示應用程式查詢 Microsoft Graph API 以擷取使用者的群組成員資格。

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

BulkCreateGroups.ps1使用 [應用程式建立腳本] 資料夾中提供的，以協助測試超額案例。

注意

傳回的 URL 會是 Azure AD Graph URL（也就是 graph.windows.net）。服務應該改用 idtyp 選擇性宣告（可識別令牌是應用程式或 app+使用者令牌），來建構 Microsoft Graph URL 來查詢群組的完整清單，而不是依賴此 URL。

v1.0 基本宣告

如果適用，v1.0 令牌會包含下列宣告，但預設不包含 v2.0 令牌。若要針對 v2.0 使用這些宣告，應用程式會使用選擇性宣告來要求這些宣告。

索賠	格式	描述
`ipaddr`	String	使用者從中驗證的IP位址。
`onprem_sid`	字串，以 SID 格式	如果使用者具有內部部署驗證，則此宣告會提供其 SID。將此宣告用於舊版應用程式中的授權。
`pwd_exp`	int，Unix 時間戳	指出用戶的密碼何時過期。
`pwd_url`	String	用戶可以重設其密碼的URL。
`in_corp`	boolean	訊號指出用戶端是否從公司網路登入。
`nickname`	String	使用者的另一個名稱，與名字或姓氏分開。
`family_name`	String	提供使用者物件上定義的使用者姓氏、姓氏或姓氏。
`given_name`	String	提供使用者物件上設定的第一個或指定用戶名稱。
`upn`	String	用戶的用戶名稱。可能是電話號碼、電子郵件位址或未格式化的字串。僅用於顯示用途，並在重新驗證案例中提供用戶名稱提示。

amr 宣告

身分識別可以透過不同的方式進行驗證，這可能與應用程式相關。宣告 amr 是一個陣列，可以包含多個專案，例如 ["mfa", "rsa", "pwd"]，用於使用密碼和 Authenticator 應用程式的驗證。

值	Description
`pwd`	密碼驗證，可以是使用者的 Microsoft 密碼或應用程式的客戶端密碼。
`rsa`	驗證是以 RSA 金鑰證明為基礎，例如使用 Microsoft Authenticator 應用程式。這個值也表示在驗證中使用自我簽署 JWT 搭配服務擁有的 X509 憑證。
`otp`	使用電子郵件或簡訊的一次性密碼。
`fed`	表示使用同盟驗證判斷提示（例如 JWT 或 SAML）。
`wia`	Windows 整合式驗證
`mfa`	表示使用 Multi-Factor Authentication。包含此宣告存在時的其他驗證方法。
`ngcmfa`	相當於 `mfa`，用於布建特定進階認證類型。
`wiaormfa`	使用者使用 Windows 或 MFA 認證進行驗證。
`none`	表示沒有完成的驗證。

下一步

深入瞭解 Microsoft Entra ID 中使用的存取令牌。