選擇性宣告參考

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

• 選取要包含在應用程式權杖中的宣告。
• 變更 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	如果使用者是租用戶中的來賓，則預設會包含此值。 若為受管理的使用者 (租用戶內的使用者)，則必須透過此選擇性宣告，或使用 OpenID 範圍 (僅限 v2.0) 來要求此值。 不保證此值是正確的，而且其可在一段時間內變動 - 永不將其用於授權或儲存使用者的資料。 如需詳細資訊，請參閱驗證使用者是否具有存取此資料的權限。 如果您使用電子郵件宣告進行授權，建議您執行移轉以移至更安全的宣告。 如果您的應用程式中需要可定址的電子郵件地址，請使用此宣告作為建議或預先填入您的 UX，直接向使用者要求此資料。
fwd	IP 位址	JWT		新增發出要求之用戶端的原始位址 (位於 VNET 內部時)。
groups	群組宣告的選擇性格式化	JWT、SAML		groups 宣告會與應用程式資訊清單 (也必須設定) 中的 GroupMembershipClaims 設定搭配使用。
idtyp	權杖類型	JWT 存取權杖	特殊：只在僅限應用程式的存取權杖中	當權杖是僅限應用程式權杖時，值是 app。 此宣告是 API 判斷權杖是應用程式權杖還是應用程式 + 使用者權杖的最精確方式。
login_hint	登入提示	JWT	MSA、Microsoft Entra ID	以 base64 編碼的不透明、可靠登入提示宣告。 請勿修改此值。 此宣告是在所有流程中用於 login_hint OAuth 參數來取得 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)。 請改用下列識別碼權杖宣告，向使用者顯示登入狀態：適用於 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 Entra ID	表示取得權杖的用戶端應用程式是否能夠處理宣告挑戰。 其通常與 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 特有的選擇性宣告集

使用 v1 權杖格式的應用程式可以使用 v2 權杖格式的部分增強功能，因為其有助於改善安全性和可靠性。 這些改善項目只適用於 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 格式發出資源 (API) 的用戶端識別碼作為 aud 宣告，而不是與執行階段相依。 例如，如果資源設定此旗標，且其用戶端識別碼是 00001111-aaaa-2222-bbbb-3333cccc4444，則任何要求該資源存取權杖的應用程式都會收到 aud 為 00001111-aaaa-2222-bbbb-3333cccc4444 的存取權杖。 若未設定此宣告，API 可能會取得權杖，其 aud 宣告為 api://MyApi.com、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 宣告，還附上其他的主租用戶和資源租用戶資訊。 只有當使用者是租用戶中的來賓時 (使用不同的 IDP 進行驗證)，才會變更權杖中的 upn 宣告。

另請參閱

• 存取權杖
• 識別碼權杖

下一步

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