可选声明引用

可以使用可选声明来：

• 选择要包含在应用程序的令牌中的声明。
• 更改Microsoft标识平台在令牌中返回的某些声明的行为。
• 添加和访问应用程序的自定义声明。

虽然 v1.0 和 v2.0 格式令牌和 SAML 令牌都支持可选声明，但它们在从 v1.0 移动到 v2.0 时提供大部分值。 在Microsoft标识平台中，使用较小的令牌大小来确保客户端的最佳性能。 因此，以前包含在访问令牌和 ID 令牌中的多个声明不再存在于 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	身份验证上下文 ID	JWT	Microsoft Entra ID	指示持有者有资格执行的操作的身份验证上下文 ID。 可以使用身份验证上下文 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 确定令牌是应用令牌还是应用+用户令牌的最准确方法。
login_hint	登录提示	JWT	MSA，Microsoft Entra ID	基本 64 编码的不透明可靠登录提示声明。 请勿修改此值。 此声明是用于所有流中用于获取 SSO 的 login_hint OAuth 参数的最佳值。 它可以在应用程序之间传递，以帮助他们以无提示方式 SSO - 应用程序 A 可以登录用户、读取 login_hint 声明，然后将声明和当前租户上下文发送到查询字符串中的应用程序 B，或者在用户选择将用户带到应用程序 B 的链接上时将其发送到应用程序 B。为了避免争用条件和可靠性问题，login_hint 声明 不会 包括用户的当前租户，并在使用时默认为用户的主租户。 在用户来自另一个租户的来宾方案中，必须在登录请求中提供租户标识符。 并将其传递给你与之合作的应用。 此声明适用于 SDK 的现有 login_hint 功能，但它公开。
tenant_ctry	资源租户的国家/地区	JWT		与管理员在租户级别设置的 ctry 相同。还必须是标准双字母值。
tenant_region_scope	资源租户的区域	JWT
upn	UserPrincipalName	JWT、SAML		可用于 username_hint 参数的用户的标识符。 不是用户的持久标识符，不应用于授权或唯一标识用户信息（例如，作为数据库密钥）。 而是使用用户对象 ID（oid）作为数据库密钥。 有关详细信息，请参阅 通过验证声明来保护应用程序和 API。 使用 备用登录 ID 登录的用户不应显示其用户主体名称（UPN）。 请改用以下 ID 令牌声明向用户显示登录状态：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	零接触部署 ID	JWT		用于 Windows AutoPilot的设备标识。

警告

切勿使用 email 或 upn 声明值来存储或确定访问令牌中的用户是否应有权访问数据。 此类可变声明值可能会随时间而变化，从而使它们不安全且不可靠。

v2.0 特定的可选声明集

这些声明始终包含在 v1.0 令牌中，但不包括在 v2.0 令牌中，除非已请求。 这些声明仅适用于 JWT（ID 令牌和访问令牌）。

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。 而是使用用户对象 ID（oid）作为数据库密钥。 使用 备用登录 ID 登录的用户不应显示其用户主体名称（UPN）。 请改用以下 preferred_username 声明向用户显示登录状态。	需要 profile 范围。

v1.0 特定的可选声明集

v2 令牌格式的一些改进可用于使用 v1 令牌格式的应用，因为它们有助于提高安全性和可靠性。 这些改进仅适用于 JWT，不适用于 SAML 令牌。

JWT 声明	名字	描述	笔记
aud	观众	始终存在于 JWT 中，但在 v1 访问令牌中，它可以以各种方式发出 -- 任何 appID URI，无论是否带有尾随斜杠，以及资源的客户端 ID。 执行令牌验证时，这种随机化可能很难进行编码。 对此声明使用 additionalProperties，以确保它始终设置为 v1 访问令牌中的资源的客户端 ID。	仅限 v1 JWT 访问令牌
preferred_username	首选用户名	在 v1 令牌中提供首选用户名声明。 此声明使应用能够更轻松地提供用户名提示并显示人工可读的显示名称，而不考虑其令牌类型。 建议使用此可选声明，而不是使用 upn 或 unique_name。	v1 ID 令牌和访问令牌

可选声明的 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 令牌或版本 ID 令牌中无效，其中 aud 声明始终为客户端 ID。 使用此配置来确保 API 可以更轻松地执行受众验证。 与影响访问令牌的所有可选声明一样，请求中的资源必须设置此可选声明，因为资源拥有访问令牌。
	use_guid	以 GUID 格式发出资源（API）的客户端 ID，因为 aud 声明始终而不是依赖于运行时。 例如，如果资源设置此标志，并且其客户端 ID 为 00001111-aaaa-2222-bbbb-3333cccc4444，则请求该资源访问令牌的任何应用都会收到一个 aud：00001111-aaaa-2222-bbbb-3333cccc4444的访问令牌。 如果没有此声明集，API 可以获取具有 api://MyApi.com、api://MyApi.com/、api://myapi.com/AdditionalRegisteredField 或任何其他值作为该 API 的应用 ID URI 以及资源的客户端 ID 的 aud 声明的令牌。
idtyp		此声明用于获取令牌类型（应用、用户、设备）。 默认情况下，它仅针对仅限应用的令牌发出。 与影响访问令牌的所有可选声明一样，请求中的资源必须设置此可选声明，因为资源拥有访问令牌。
	include_user_token	为用户令牌发出 idtyp 声明。 如果没有 idtyp 声明集的此可选附加属性，API 仅获取应用令牌的声明。

additionalProperties 示例

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

此 optionalClaims 对象会导致返回给客户端的 ID 令牌包含具有其他主租户和资源租户信息的 upn 声明。 仅当用户是租户中的来宾（使用其他 IDP 进行身份验证）时，令牌中的 upn 声明才会更改。

另请参阅

• 访问令牌
• ID 令牌

后续步骤

• 详细了解如何 配置可选声明。