可选声明参考

项目
04/26/2024

使用可选声明可以：

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

虽然 v1.0 和 v2.0 格式令牌以及 SAML 令牌都支持可选声明，但从 v1.0 迁移到 v2.0 后，它们才可发挥其主要价值。在 Microsoft 标识平台中，使用了更小的令牌大小来确保客户端获得最佳性能。因此，以前包含在访问令牌和 ID 令牌中的多个声明不再在 v2.0 令牌中提供，必须根据应用程序专门请求这些声明。

帐户类型	v1.0 令牌	v2.0 令牌
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。可以使用上下文 AD 从应用程序和服务中触发对逐步身份验证的需求。通常与 `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	进行 base64 编码的不透明的可靠登录提示声明。请不要修改此值。此声明是用于在所有流中获取 SSO 的 `login_hint` OAuth 参数的最佳值。它还可以在应用程序之间传递，以帮助进行无提示 SSO - 应用程序 A 可以让某个用户登录，读取 `login_hint` 声明，然后当用户选择指向应用程序 B 的链接时，应用程序 A 通过查询字符串或片段将声明和当前租户上下文发送到应用程序 B。为避免争用条件和可靠性问题，`login_hint` 声明不包含用户的当前租户，并在使用时默认为用户的主租户。在用户来自另一个租户的来宾方案中，必须在登录请求中提供租户标识符。并将相同的内容传递给你与之合作的应用。此声明适用于 SDK 的现有 `login_hint` 功能，但它是公开的。
`sid`	会话 ID，用于基于会话的用户注销	JWT	Microsoft Entra 帐户。
`tenant_ctry`	资源租户所在的国家/地区	JWT		与 `ctry` 相同，区别是由管理员在租户级别设置。还必须是标准的双字母值。
`tenant_region_scope`	资源租户的区域	JWT
`upn`	UserPrincipalName	JWT、SAML		可与 `username_hint` 参数一起使用的用户标识符。不是用户的持久标识符，不应用于授权或唯一标识用户信息（例如，用作数据库密钥）。应改用用户对象 ID (`oid`) 作为数据库密钥。有关详细信息，请参阅通过验证声明保护应用程序和 API。不应向使用备用登录 ID 登录的用户显示其用户主体名称 (UPN)。应改用以下 ID 令牌声明向用户显示登录状态：`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)。 SAML/WS 联合身份验证帐户没有经过验证的域。若要在令牌中返回此声明，则必须存在 `email` 声明。
`xms_pdl`	首选数据位置	JWT		对于多地域租户，首选数据位置是显示用户所在地理区域的三字母代码。
`xms_pl`	用户首选语言	JWT		用户的首选语言（如果已设置）。在来宾访问方案中，源自其主租户。已格式化 LL-CC（“zh-cn”）。
`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 得到的令牌中的 `aud` 声明可能为 `api://MyApi.com`、`api://MyApi.com/`、`api://myapi.com/AdditionalRegisteredField`，或者设置为该 API 的应用 ID URI 和资源的客户端 ID 的任何其他值。
`idtyp`		此声明用于获取令牌类型（应用、用户、设备）。默认情况下，它仅针对仅限应用的令牌发出。与影响访问令牌的所有可选声明一样，请求中的资源必须设置此可选声明，因为资源拥有访问令牌。
	`include_user_token`	发出针对用户令牌的 `idtyp` 声明。如果没有为 idtyp 声明集使用此可选附加属性，则 API 仅获取针对应用令牌的声明。

`additionalProperties` 实例

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

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

请参阅

后续步骤

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

通过