選擇性宣告參考

您可以使用選擇性宣告來：

• 選取要包含在應用程式令牌中的宣告。
• 變更 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 選擇性宣告集

下表列出依預設可供使用之應用程式的選用宣告集。 您可以使用延伸模組屬性和目錄延伸模組中的自訂數據，為您的應用程式新增選擇性宣告。 當您將宣告新增至存取令牌時，宣告會套用至應用程式所要求的存取令牌（Web API），而不是應用程式所要求的宣告。 無論用戶端如何存取您的 API，正確的數據都存在於用來針對 API 進行驗證的存取令牌中。

注意

這些宣告的大多數都可以包含在 v1.0 和 v2.0 令牌的 JWT 中，但不包括 SAML 令牌，但令牌類型數據行中所指出的位置除外。 取用者帳戶支持這些宣告的子集，並標示在 [使用者類型] 資料行中。 列出的許多宣告不適用於取用者使用者（他們沒有租使用者，因此 tenant_ctry 沒有值）。

下表列出 v1.0 和 v2.0 選擇性宣告集。

名稱	描述	語彙基元類型	使用者類型	備註
acct	租使用者中的用戶帳戶狀態	JWT、SAML		如果使用者是租使用者的成員，則值為 0。 如果是來賓，則值為 1。
acrs	驗證內容識別碼	JWT	Microsoft Entra ID	指出持有人有資格執行之作業的驗證內容標識碼。 驗證內容標識碼可用來觸發來自應用程式和服務內之逐步驗證的需求。 通常與宣告一 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 編碼的不透明可靠登入提示宣告。 請勿修改此值。 此宣告是所有流程中 OAuth login_hint 參數用來取得 SSO 的最佳值。 它可以在應用程式之間傳遞，以協助他們以無訊息方式 SSO - 應用程式 A 可以登入使用者、讀取 login_hint 宣告，然後將宣告和目前的租使用者內容傳送至查詢字串或片段中的應用程式 B，當使用者選取將他們帶到應用程式 B 的連結時。為避免競爭狀況和可靠性問題， login_hint 宣告 不包含 使用者的目前租使用者，而且會在使用時預設為使用者的主租使用者。 在使用者來自另一個租用戶的來賓案例中，必須在登入要求中提供租使用者標識碼。 並將相同的傳遞給您合作的應用程式。 此宣告旨在與 SDK 的現有 login_hint 功能搭配使用，但已公開。
sid	會話標識碼，用於每一會話用戶註銷	JWT	個人和 Microsoft Entra 帳戶。
tenant_ctry	資源租用戶的國家/地區	JWT		與 ctry 系統管理員在租用戶層級設定的相同。也必須是標準雙字母值。
tenant_region_scope	資源租用戶的區域	JWT
upn	UserPrincipalName	JWT、SAML		可與參數搭配 username_hint 使用之使用者的標識碼。 不是使用者的持久標識碼，不應該用於授權或唯一識別使用者資訊（例如，作為資料庫密鑰）。 請改用使用者物件識別碼 （oid） 作為資料庫金鑰。 如需詳細資訊，請參閱 驗證宣告來保護應用程式和API。 使用替代登入標識碼登入的使用者不應該顯示其用戶主體名稱 （UPN）。 請改用下列標識元令牌宣告，向用戶顯示登入狀態： preferred_username 或 unique_name 針對 v1 令牌和 preferred_username v2 令牌。 雖然此宣告會自動包含，但您可以將它指定為選擇性宣告，以附加其他屬性，以在來賓使用者案例中修改其行為。 您應該使用 login_hint 宣告來 login_hint 使用 - UPN 等人類可讀取的標識碼是不可靠的。
verified_primary_email	來源自使用者的 PrimaryAuthoritativeEmail	JWT
verified_secondary_email	來源自使用者的 SecondaryAuthoritativeEmail	JWT
vnet	VNET 規範資訊。	JWT
xms_cc	用戶端功能	JWT	Microsoft Entra ID	指出取得令牌的用戶端應用程式是否能夠處理宣告挑戰。 它通常會與宣告 acrs搭配使用。 此宣告通常用於條件式存取和持續存取評估案例。 令牌發出的資源伺服器或服務應用程式，可控制令牌中是否有此宣告。 存取令牌中的 值 cp1 是識別用戶端應用程式能夠處理宣告挑戰的權威方式。 如需詳細資訊，請參閱 宣告挑戰、宣告要求和用戶端功能。
xms_edov	布爾值，指出使用者的電子郵件網域擁有者是否已驗證。	JWT		如果電子郵件屬於用戶帳戶所在的租使用者，且租用戶系統管理員已完成網域驗證，則會將電子郵件視為已驗證網域。 此外，電子郵件必須來自 Microsoft 帳戶（MSA）、Google 帳戶，或使用單次密碼 （OTP） 流程進行驗證。 Facebook 和 SAML/WS-Fed 帳戶 沒有 已驗證的網域。 若要讓此宣告在令牌中傳回，則需要宣告的存在 email 。
xms_pdl	慣用的數據位置	JWT		對於多地理位置租使用者，慣用的數據位置是三個字母的程序代碼，其中顯示使用者所在的地理區域。 如需詳細資訊，請參閱 Microsoft Entra 連線 慣用數據位置的相關文件。
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 識別碼中支援。 profile需要範圍。
given_name	名字	提供使用者物件上設定的第一個或「指定」用戶名稱。 例如： "given_name": "Frank" 。	MSA 和 Microsoft Entra 識別碼中支援。 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 令牌中提供慣用的用戶名稱宣告。 此宣告可讓應用程式更輕鬆地提供使用者名稱提示，並顯示人類可讀的顯示名稱，而不論其令牌類型為何。 建議您使用此選擇性宣告，而不是使用 或 upnunique_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 可以取得令牌，其宣告api://MyApi.com為 aud 、 api://MyApi.com/api://myapi.com/AdditionalRegisteredField 或任何其他值設定為該 API 的應用程式識別碼 URI，以及資源的用戶端識別碼。
idtyp		此宣告是用來取得令牌的類型（應用程式、使用者、裝置）。 根據預設，它只會針對僅限應用程式令牌發出。 如同影響存取令牌的所有選擇性宣告，要求中的資源必須設定此選擇性宣告，因為資源擁有存取令牌。
	include_user_token	發出使用者令牌的 idtyp 宣告。 如果沒有idtyp宣告集的這個選擇性額外屬性，API 只會取得應用程式令牌的宣告。

additionalProperties 例子

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

這個 optionalClaims 物件會導致傳回給客戶端的標識碼令牌包含 upn 宣告與其他主租用戶和資源租用戶資訊。 upn只有在使用者是租使用者中的來賓時，才會在令牌中變更宣告（使用不同的 IDP 進行驗證）。

另請參閱

• 存取權杖
• 標識元令牌

下一步

• 深入瞭解如何 設定選擇性宣告。