選擇性宣告參考
您可以使用選擇性宣告來：
- 選取要包含在應用程式令牌中的宣告。
- 變更Microsoft身分識別平臺在令牌中傳回之特定宣告的行為。
- 新增和存取應用程式的自定義宣告。
雖然 v1.0 和 v2.0 格式令牌和 SAML 令牌都支持選擇性宣告，但它們在從 v1.0 移至 v2.0 時提供大部分的值。 在Microsoft身分識別平臺中，會使用較小的令牌大小來確保用戶端的最佳效能。 因此，先前包含在存取和標識碼令牌中的數個宣告不再存在於 v2.0 令牌中，而且必須依個別應用程式特別要求。
| 帳戶類型 | v1.0 令牌 | v2.0 令牌 |
|---|---|---|
| 個人Microsoft帳戶 | N/A | 支援 |
| Microsoft Entra 帳戶 | 支援 | 支援 |
v1.0 和 v2.0 選擇性宣告集
下表列出依預設可供使用之應用程式的選用宣告集。 您可以使用延伸模組屬性和目錄延伸模組中的自訂數據，為您的應用程式新增選擇性宣告。 當您將宣告新增至存取令牌時，宣告會套用至應用程式 要求
注意
這些宣告的大多數都可以包含在 v1.0 和 v2.0 令牌的 JWT 中，但不包括 SAML 令牌，但令牌類型數據行中所指出的位置除外。 取用者帳戶支持這些宣告的子集，並標示在 [使用者類型] 資料行中。 列出的許多宣告不適用於取用者使用者（他們沒有租使用者，因此 tenant_ctry 沒有值）。
下表列出 v1.0 和 v2.0 選擇性宣告集。
| 名字 | 描述 | 令牌類型 | 用戶類型 | 筆記 |
|---|---|---|---|---|
acct |
租使用者中的用戶帳戶狀態 | JWT、SAML | 如果使用者是租使用者的成員，則值會 0。 如果是來賓，則值會 1。 |
|
acrs |
驗證內容識別碼 | JWT | Microsoft項目標識碼 | 指出持有人有資格執行之作業的驗證內容標識碼。 驗證內容標識碼可用來觸發來自應用程式和服務內之逐步驗證的需求。 通常與 xms_cc 宣告一起使用。 |
auth_time |
使用者上次驗證的時間。 | JWT | ||
ctry |
用戶的國家/地區 | JWT | 如果存在，而且域的值是標準雙字母國家/地區代碼，例如FR、JP、SZ等，則會傳回此宣告。 | |
email |
此使用者的報告電子郵件位址 | JWT、SAML | MSA，Microsoft Entra ID | 如果使用者是租使用者中的來賓，則預設會包含此值。 針對受控使用者（租使用者內的使用者），它必須透過此選擇性宣告要求，或只有在 v2.0 上才具有 OpenID 範圍。 此值不保證正確，而且會隨著時間變動而變動-永遠不要用於授權或儲存用戶的數據。 如需詳細資訊，請參閱 驗證使用者有權存取此資料。 如果您使用電子郵件宣告進行授權，建議您 執行移轉，以移至更安全的宣告。 如果您需要應用程式中可尋址的電子郵件位址，請直接向使用者要求此數據，使用此宣告作為建議或預先填入您的UX。 |
fwd |
IP位址 | JWT | 新增要求用戶端的原始位址（在 VNET 內時）。 | |
groups |
群組宣告的選擇性格式設定 | JWT、SAML |
groups 宣告會與 應用程式指令清單中的 GroupMembershipClaims 設定搭配使用，也必須加以設定。 |
|
idtyp |
令牌類型 | JWT 存取令牌 | 特殊：僅在僅限應用程式存取令牌中 | 當令牌是僅限應用程式令牌時，此值會 app。 此宣告是 API 判斷令牌是否為應用程式令牌或 app+使用者令牌的最精確方式。 |
login_hint |
登入提示 | JWT | MSA，Microsoft Entra ID | 基礎為 64 編碼的不透明可靠登入提示宣告。 請勿修改此值。 此宣告是用於所有流程中 login_hint OAuth 參數以取得 SSO 的最佳值。 它可以在應用程式之間傳遞，以協助他們以無訊息方式 SSO - 應用程式 A 也可以登入使用者、讀取 login_hint 宣告，然後在使用者選取將他們帶到應用程式 B 的連結時，將宣告和目前的租用戶內容傳送至應用程式 B。為了避免競爭狀況和可靠性問題，login_hint 宣告 不會 包含使用者的目前租使用者，並在使用時預設為使用者的主租使用者。 在使用者來自另一個租用戶的來賓案例中，必須在登入要求中提供租使用者標識碼。 並將相同的傳遞給您合作的應用程式。 此宣告旨在與 SDK 的現有 login_hint 功能搭配使用，但已公開。 |
tenant_ctry |
資源租用戶的國家/地區 | JWT | 與系統管理員在租用戶層級設定的 ctry 相同。也必須是標準雙字母值。 |
|
tenant_region_scope |
資源租用戶的區域 | JWT | ||
upn |
UserPrincipalName | JWT、SAML | 可以搭配 username_hint 參數使用之使用者的標識碼。 不是使用者的持久標識碼，不應該用於授權或唯一識別使用者資訊（例如，作為資料庫密鑰）。 請改用使用者物件識別碼 （oid） 作為資料庫金鑰。 如需詳細資訊，請參閱 驗證宣告來保護應用程式和 API。 使用 替代登入識別碼的使用者不應該顯示其用戶主體名稱 （UPN）。 請改用下列標識元令牌宣告向用戶顯示登入狀態：v1 令牌的 preferred_username 或 unique_name，以及 v2 令牌的 preferred_username。 雖然此宣告會自動包含，但您可以將它指定為選擇性宣告，以附加其他屬性，以在來賓使用者案例中修改其行為。 您應該使用 login_hint 宣告來 login_hint 使用 - UPN 等人類可讀取的識別碼是不可靠的。 |
|
verified_primary_email |
來源自使用者的 PrimaryAuthoritativeEmail | JWT | ||
verified_secondary_email |
來源自使用者的 SecondaryAuthoritativeEmail | JWT | ||
vnet |
VNET 規範資訊。 | JWT | ||
xms_cc |
用戶端功能 | JWT | Microsoft項目標識碼 | 指出取得令牌的用戶端應用程式是否能夠處理宣告挑戰。 它通常會與宣告 acrs搭配使用。 此宣告通常用於條件式存取和持續存取評估案例。 令牌發出的資源伺服器或服務應用程式，可控制令牌中是否有此宣告。 存取令牌中的 cp1 值是識別用戶端應用程式能夠處理宣告挑戰的權威方式。 如需詳細資訊，請參閱 宣告挑戰、宣告要求和用戶端功能。 |
xms_edov |
布爾值，指出使用者的電子郵件網域擁有者是否已驗證。 | JWT | 如果電子郵件屬於用戶帳戶所在的租使用者，且租用戶系統管理員已完成網域驗證，則會將電子郵件視為已驗證網域。 此外，電子郵件必須來自Microsoft帳戶（MSA）、Google 帳戶，或使用單次密碼 （OTP） 流程進行驗證。 Facebook 和 SAML/WS-Fed 帳戶 未 已驗證網域。 若要在令牌中傳回此宣告，則需要有 email 宣告。 |
|
xms_pdl |
慣用的數據位置 | JWT | 對於多地理位置租使用者，慣用的數據位置是三個字母的程序代碼，其中顯示使用者所在的地理區域。 如需詳細資訊，請參閱 Microsoft Entra Connect 檔，以瞭解慣用資料位置。 | |
xms_pl |
使用者慣用語言 | JWT | 如果使用者慣用的語言已設定，則為 。 從其主租使用者來源，在來賓存取案例中。 格式化 LL-CC （“en-us]。 | |
xms_tpl |
租使用者慣用語言 | JWT | 如果已設定，則為資源租使用者慣用的語言。 格式化的 LL （“en” ） | |
ztdid |
零觸控式部署標識碼 | JWT | 用於 Windows AutoPilot的裝置身分識別。 |
警告
請勿使用 email 或 upn 宣告值來儲存或判斷存取令牌中的使用者是否應該能夠存取數據。 這類可變動的宣告值可能會隨著時間而變更，使其不安全且不可靠。
v2.0 特定選擇性宣告集
這些宣告一律包含在 v1.0 令牌中，但除非要求，否則不包含在 v2.0 令牌中。 這些宣告僅適用於 JWT（識別元令牌和存取令牌）。
| JWT 宣告 | 名字 | 描述 | 筆記 |
|---|---|---|---|
ipaddr |
IP位址 | 用戶端從中登入的IP位址。 | |
onprem_sid |
內部部署安全性標識碼 | ||
pwd_exp |
密碼到期時間 | 密碼到期之 iat 宣告中的秒數。 只有在密碼即將到期時，才會包含此宣告（如密碼原則中的「通知天數」所定義）。 |
|
pwd_url |
變更密碼 URL | 用戶可以瀏覽以變更其密碼的 URL。 只有在密碼即將到期時，才會包含此宣告（如密碼原則中的「通知天數」所定義）。 | |
in_corp |
公司網路內部 | 從公司網路登入客戶端時發出訊號。 如果沒有，則不會包含宣告。 | 根據 MFA 中的 受信任 IP 設定。 |
family_name |
姓 | 提供用戶物件中所定義之使用者的姓氏、姓氏或姓氏。 例如，"family_name":"Miller"。 |
MSA 和 Microsoft Entra ID 中支援。 需要 profile 範圍。 |
given_name |
名字 | 提供使用者物件上設定的第一個或「指定」用戶名稱。 例如，"given_name": "Frank"。 |
MSA 和 Microsoft Entra ID 中支援。 需要 profile 範圍。 |
upn |
用戶主體名稱 | 可以搭配 username_hint 參數使用之使用者的標識碼。 不是使用者的持久標識碼，不應該用於授權或唯一識別使用者資訊（例如，作為資料庫密鑰）。 如需詳細資訊，請參閱 驗證宣告來保護應用程式和 API。 請改用使用者物件識別碼 （oid） 作為資料庫金鑰。 使用 替代登入識別碼的使用者不應該顯示其用戶主體名稱 （UPN）。 請改用下列 preferred_username 宣告，向用戶顯示登入狀態。 |
需要 profile 範圍。 |
v1.0 特定選擇性宣告集
v2 令牌格式的一些改善可供使用 v1 令牌格式的應用程式使用，因為它們有助於改善安全性和可靠性。 這些改進僅適用於 JWT，不適用於 SAML 令牌。
| JWT 宣告 | 名字 | 描述 | 筆記 |
|---|---|---|---|
aud |
觀眾 | 一律存在於 JWT 中，但在 v1 存取令牌中，它可以以各種方式發出 -- 任何 appID URI，無論是否有尾端斜線，以及資源的用戶端識別碼。 執行令牌驗證時，此隨機化可能很難進行程序代碼。 針對此宣告使用 additionalProperties，以確保它一律設定為 v1 存取令牌中的資源用戶端識別符。 |
僅限 v1 JWT 存取令牌 |
preferred_username |
慣用的用戶名稱 | 在 v1 令牌中提供慣用的用戶名稱宣告。 此宣告可讓應用程式更輕鬆地提供使用者名稱提示，並顯示人類可讀的顯示名稱，而不論其令牌類型為何。 建議您使用此選擇性宣告，而不是使用、upn 或 unique_name。 |
v1識別元令牌和存取令牌 |
選擇性宣告的 additionalProperties
某些選擇性宣告可以設定為變更傳回宣告的方式。 這些 additionalProperties 大多用來協助移轉具有不同數據期望的內部部署應用程式。 例如，include_externally_authenticated_upn_without_hash 有助於處理UPN中無法處理哈希標記 （#） 的用戶端。
| 屬性名稱 |
additionalProperty 名稱 |
描述 |
|---|---|---|
upn |
可用於 SAML 和 JWT 回應，以及 v1.0 和 v2.0 令牌。 | |
include_externally_authenticated_upn |
包含儲存在資源租使用者中的來賓UPN。 例如，foo_hometenant.com#EXT#@resourcetenant.com。 |
|
include_externally_authenticated_upn_without_hash |
與先前列出的相同，不同之處在於哈希標記（#）會取代為底線（_），例如 foo_hometenant.com_EXT_@resourcetenant.com。 |
|
aud |
在 v1 存取令牌中，此宣告用來變更 aud 宣告的格式。 此宣告在 v2 令牌或版本標識元令牌中沒有任何作用，其中 aud 宣告一律為用戶端標識符。 使用此組態以確保您的 API 可以更輕鬆地執行物件驗證。 如同影響存取令牌的所有選擇性宣告，要求中的資源必須設定此選擇性宣告，因為資源擁有存取令牌。 |
|
use_guid |
以 GUID 格式發出資源的用戶端標識碼，作為一律 aud 宣告，而不是與運行時間相依。 例如，如果資源設定此旗標，且其用戶端識別碼為 00001111-aaaa-2222-bbbb-3333cccc4444，則要求該資源存取令牌的任何應用程式會收到具有 aud 的存取令牌：00001111-aaaa-2222-bbbb-3333cccc4444。 如果沒有此宣告集，API 可以取得 aud 具有 api://MyApi.com、api://MyApi.com/、api://myapi.com/AdditionalRegisteredField 或任何其他值設定為該應用程式識別碼 URI 的令牌，以及資源的用戶端識別符。 |
|
idtyp |
此宣告是用來取得令牌的類型（應用程式、使用者、裝置）。 根據預設，它只會針對僅限應用程式令牌發出。 如同影響存取令牌的所有選擇性宣告，要求中的資源必須設定此選擇性宣告，因為資源擁有存取令牌。 | |
include_user_token |
發出使用者令牌的 idtyp 宣告。 如果沒有idtyp宣告集的這個選擇性額外屬性，API 只會取得應用程式令牌的宣告。 |
additionalProperties 範例
"optionalClaims": {
"idToken": [
{
"name": "upn",
"essential": false,
"additionalProperties": [
"include_externally_authenticated_upn"
]
}
]
}
這個 optionalClaims 物件會導致傳回給用戶端的標識元令牌包含與其他主租用戶和資源租使用者資訊的 upn 宣告。 只有當使用者是租使用者中的來賓時，upn 宣告才會在令牌中變更（使用不同的IDP進行驗證）。