存取權杖宣告參考
存取權杖是 JSON Web 權杖 (JWT)。 JWT 包含下列片段：
- 標頭 - 提供如何驗證權杖的相關資訊，包括權杖類型及其簽署方法的相關資訊。
- 承載 - 對於嘗試呼叫服務的使用者或應用程式，其所有相關重要資料都包含在此。
- 簽章 - 用來驗證權杖的原始資料。
各部分會以句點分隔 (.)，並各別以 Base64 編碼。
如果有值可填入宣告時，宣告才會存在。 應用程式不應該相依於目前存在的宣告。 例如 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 |
字串，Security Token Service (STS) URI | 識別可建構並傳回權杖的 STS，以及驗證使用者的 Microsoft Entra 租用戶。 如果核發的權杖是 v2.0 權杖 (請參閱 ver 宣告)，則 URI 的結尾為 /v2.0。 指出使用者是來自 Microsoft 帳戶之取用者使用者的 GUID 是 9188040d-6c67-4c5b-b112-36a304b66dad。 |
應用程式可以使用宣告的 GUID 部分來限制可登入應用程式的租用戶集合 (適用時)。 |
idp |
字串，通常是 STS URI | 記錄驗證權杖主體的身分識別提供者。 除非使用者帳戶與簽發者不在相同的租用戶中 (例如來賓)，否則此值會與簽發者宣告的值完全相同。 如果宣告不存在，請使用 iss 的值。 針對在組織內容中使用的個人帳戶 (例如獲邀使用 Microsoft Entra 租用戶的個人帳戶)，idp 宣告可能會是 'live.com' 或包含 Microsoft 帳戶租用戶 9188040d-6c67-4c5b-b112-36a304b66dad 的 STS URI。 |
|
iat |
整數，Unix 時間戳記 | 指定此權杖進行驗證的時間。 | |
nbf |
整數，Unix 時間戳記 | 指定可以處理 JWT 的時間。 | |
exp |
整數，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 |
字串 (0、1 或 2)，僅存在於 v1.0 權杖中 |
表示用戶端的驗證方法。 針對公用用戶端，值為 0。 當您使用用戶端識別碼和用戶端密碼時，值為 1。 當您使用用戶端憑證進行驗證時，值為 2。 |
|
azpacr |
字串 (0、1 或 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 會排除所有群組、值 SecurityGroup 會包括目錄角色和 Active Directory 安全性群組成員資格，而值 All 會包括安全性群組和 Microsoft 365 通訊群組。 請參閱 hasgroups 宣告，以取得搭配使用 groups 宣告與隱含授與的詳細資料。 針對其他流程，如果使用者所在的群組數目超過 150 (針對 SAML) 和 200 (針對 JWT)，則 Microsoft Entra ID 會將超額宣告新增至宣告來源。 宣告來源會指向包含使用者群組清單的 Microsoft Graph 端點。 |
這些值可用於管理存取權，例如強制執行授權以存取資源。 |
hasgroups |
布林值 | 如果有的話，則一律為 true，指出使用者是否至少在一個群組中。 如果完整 groups 宣告會將 URI 片段延伸超出 URL 長度限制 (目前為六個或更多群組)，則使用於取代隱含授與流程中 JWT 的 groups 宣告。 指出用戶端應該使用 Microsoft Graph API 來判斷使用者的群組 (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects)。 |
|
groups:src1 |
JSON 物件 | 在權杖要求對權杖而言太大時，包含使用者的完整群組清單連結。 在 JWT 中以分散式宣告形式取代 groups 宣告，在 SAML 中則以新宣告形式取代。 範例 JWT 值： "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" } |
|
sub |
String | 與權杖相關聯的主體。 例如，應用程式的使用者。 此值是不可變的，請勿重新指派或重複使用。 主體是成對識別碼，對於特定應用程式識別碼來說，主體是唯一的。 如果單一使用者使用兩個不同的用戶端識別碼登入兩個不同的應用程式，則這些應用程式會收到兩個不同的主體宣告值。 根據架構和隱私權需求，使用兩個不同的值。 另請參閱 oid 宣告，這確實會在租用戶內跨應用程式保持不變。 |
此值可用來執行授權檢查 (例如當權杖用於存取資源時)，並可做為資料庫資料表中的索引鍵。 |
oid |
字串，GUID | 要求者的不可變識別碼，而要求者是使用者或服務主體的已驗證身分識別。 此識別碼可跨應用程式唯一識別要求者。 登入相同使用者的兩個不同應用程式會在 oid 宣告中收到相同的值。 對 Microsoft 線上服務 (例如 Microsoft Graph) 進行查詢時，可以使用 oid。 Microsoft Graph 會傳回此識別碼作為所指定使用者帳戶的 id 屬性。 因為 oid 可讓多個應用程式與主體相互關聯，才能接收此宣告讓使用者使用 profile 範圍。 如果單一使用者存在於多個租用戶中，則使用者會在每個租用戶中包含不同的物件識別碼。 即使使用者以相同的認證登入每個帳戶，帳戶仍然不同。 |
此值可用來執行授權檢查 (例如當權杖用於存取資源時)，並可做為資料庫資料表中的索引鍵。 |
tid |
字串，GUID | 代表使用者要登入的租用戶。 就工作和學校帳戶而言，GUID 是使用者登入組織的不可變租用戶識別碼。 若要登入個人 Microsoft 帳戶租使用者服務 (例如 Xbox、Teams Life 或 Outlook)，值為 9188040d-6c67-4c5b-b112-36a304b66dad。 若要收到此宣告，應用程式必須要求 profile 範圍。 |
此值應該與授權決策中的其他宣告合併考慮。 |
unique_name |
字串，僅存在於 v1.0 權杖中 | 提供人類看得懂的值，用以識別權杖的主體。 | 此值在租用戶內可能不同，並且僅供顯示用途。 |
uti |
String | 權杖識別碼宣告，相當於 JWT 規格中的 jti。 區分大小寫的唯一專屬權杖識別碼。 |
|
rh |
不透明字串 | Azure 用來重新驗證權杖的內部宣告。 資源不應該使用此宣告。 | |
ver |
字串，1.0 或 2.0 |
表示存取權杖的版本。 | |
xms_cc |
字串的 JSON 陣列 | 表示取得權杖的用戶端應用程式是否能夠處理宣告挑戰。 其通常與 acrs 宣告一起使用。 此宣告通常用於條件式存取和持續性存取評估案例。 權杖發出的資源伺服器或服務應用程式，可控制權杖中是否有此宣告。 存取權杖中的 cp1 值，是識別用戶端應用程式是否能夠處理宣告挑戰的授權方式。 如需詳細資訊，請參閱宣告挑戰、宣告要求和用戶端功能。 |
注意
roles、 groupsscp和 wids 宣告不是資源如何授權使用者或應用程式的完整清單，也不是授與給呼叫端的詳盡許可權清單。 目標資源可能會使用另一種方法來授權其受保護資源的存取權。
群組超額宣告
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 選擇性宣告 (這會識別權杖是應用程式權杖或應用程式+使用者權杖) 來建構 Microsoft Graph URL，以查詢群組的完整清單，而不是依賴此 URL。
v1.0 基本宣告
v1.0 權杖包含下列宣告 (如果適用的話)，預設不是 v2.0 權杖。 若要針對 v2.0 使用這些宣告，應用程式會使用選用宣告來要求這些宣告。
| 索賠 | 格式 | 描述 |
|---|---|---|
ipaddr |
String | 從中進行使用者驗證的 IP 位址。 |
onprem_sid |
字串，採 SID 格式 | 如果使用者具有內部部署驗證，此宣告會提供其 SID。 使用此宣告以進行舊版應用程式中的授權。 |
pwd_exp |
整數，Unix 時間戳記 | 表示使用者密碼到期的時間。 |
pwd_url |
String | 使用者可重設其密碼的 URL。 |
in_corp |
boolean | 指出用戶端是否從公司網路登入。 |
nickname |
String | 使用者的另一個名稱 (與名字或姓氏不同)。 |
family_name |
String | 提供使用者的姓氏 (如使用者物件中所定義)。 |
given_name |
String | 提供使用者的名字 (如使用者物件上所設定)。 |
upn |
String | 使用者的使用者名稱。 可能是電話號碼、電子郵件地址或未格式化的字串。 只用於顯示用途，並在重新驗證情節中提供使用者名稱提示。 |
amr 宣告
身分識別可以透過不同的方式進行驗證，而這些方式可能與應用程式相關。 amr 宣告為陣列，其中可包含多個項目，例如 ["mfa", "rsa", "pwd"]，適用於同時使用密碼和驗證器應用程式的驗證。
| 值 | Description |
|---|---|
pwd |
密碼驗證，可以是使用者的 Microsoft 密碼或應用程式的用戶端祕密。 |
rsa |
驗證會以 RSA 金鑰證明為基礎，例如使用 Microsoft Authenticator 應用程式。 此值也表示在驗證中使用自我簽署 JWT 搭配擁有 X509 憑證的服務。 |
otp |
使用電子郵件或簡訊的單次密碼。 |
fed |
表示使用同盟驗證判斷提示 (例如 JWT 或 SAML)。 |
wia |
Windows 整合式驗證 |
mfa |
指出多重要素驗證的使用方式。 當此宣告存在時，會包括其他驗證方法。 |
ngcmfa |
相當於mfa，用來佈建的某些進階的認證類型。 |
wiaormfa |
使用者已使用 Windows 或 MFA 認證來進行驗證。 |
none |
表示沒有完成的驗證。 |