選擇性宣告參考

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

  • 選取要包含在應用程式令牌中的宣告。
  • 改變某些聲明的行為，這些聲明是 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 編碼的不透明可靠登入提示宣告。 請勿修改此值。 此宣告是用於所有流程中 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 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 範圍。
amr 認證方法參考 識別代幣主體的鑑定方式。 關於 Microsoft Entra ID 對每種認證方法所發出的數值，請參見 Microsoft Entra 認證方法的 AMR 值。

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進行驗證）。

Microsoft Entra 認證方法的 AMR 值

amr （認證方法參考）主張指出使用者如何進行認證。 amr Salesforce應用程式預設會收到理賠，因此這些應用程式不需要設定變更。 對於所有其他 SAML 應用程式，應用程式管理員必須將附加屬性amr的選填include_granular_amr權利要求加入應用程式註冊，才能請求 AMR 權利要求。 multipleauthn且mfa值僅在使用者完成多重驗證（MFA）後才會發出。

關於 SAML，請參見 authnmethodreferences 以獲得更多細節。

關於 OIDC，請參考下表，列出 authnmethodsreferences Microsoft Entra ID 對每種認證方法所傳送的值：

Microsoft Entra 驗證方法 OIDC v2.0 代幣主張
密碼 pwd
認證推送 rsa、ngcmfa、mfa
認證器 TOTP totp、mfa
硬體身份驗證 OATH 憑證 hotp、mfa
手機登入（無密碼認證器應用程式） swk、rsa、mfa
SMS sms、mfa
通話 tel、mfa
Email emailotp、mfa
FIDO2 安全金鑰（PRMFA） fido、mfa
通行金鑰（裝置綁定）（PRMFA） fido、mfa
通行金鑰（同步）（PRMFA） fido、mfa
Windows Hello 企業版（PRMFA） hwk、mfa、ngcmfa
基於憑證的認證（PRMFA for Multi-factor CBA） hwk（多因子CBA）或x509（單因子CBA）， mfarsa
臨時存取密碼 (TAP) otp、mfa
Windows 整合認證（Kerberos） wia
基於裝置的 X509 認證 x509

Microsoft在索amr賠中同時包含x509單因素 Certificate-Based 認證（CBA）及基於裝置的X.509認證。 然而，僅僅存在 x509 並不符合抗釣魚多重認證（PRMFA）。 為符合 PRMFA 要求，使用者還需完成額外的多重驗證因子，該因素會在認證情境中反映於其他認證方法指標中。 Microsoft Entra ID 會將amr外部 MFA 提供者傳送的值以及 amr Microsoft Entra ID 中執行的驗證方法值一併轉發。 欲了解更多資訊，請參閱 支援的AMR主張。

另請參閱

後續步驟

  • 深入瞭解 設定選擇性宣告。
  • 上次更新時間：