配置可选声明

项目
06/14/2024

Microsoft Entra 返回的令牌会保持较小的大小，以确保请求令牌的客户端获得最佳性能。因此，默认情况下，多个声明在令牌中不复存在，并且必须根据应用程序专门请求这些声明。

可以通过 Microsoft Entra 管理中心的应用程序 UI 或清单为应用程序配置可选声明。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
完成快速入门：注册应用程序

在应用程序中配置可选声明

至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“应用注册”。
请根据使用场景和期望的结果选择要为其配置可选声明的应用程序。

通过应用 UI 操作
通过清单操作

在“管理”下，选择“令牌配置” 。
选择“添加可选声明”。
选择要配置的令牌类型，例如 Access。
选择要添加的可选声明。
选择添加。

在“管理”下，选择“清单” 。此时会打开一个基于 Web 的清单编辑器，可在其中编辑清单。（可选）可以选择“下载”并在本地编辑清单，然后使用“上传”将清单重新应用到应用程序。如果文件不包含 optionalClaims 属性，可以添加它。

以下应用程序清单条目将 auth_time、ipaddr 和 upn 可选声明添加到 ID、访问和 SAML 令牌。

"optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}

完成后，选择“保存”。现在，指定的可选声明包含在应用程序的令牌中。

optionalClaims 对象声明应用程序请求的可选声明。应用程序可以配置在 ID 令牌、访问令牌和 SAML 2 令牌中返回的可选声明。应用程序可以配置为要在每种令牌类型中返回一组不同的可选声明。

名称	Type	说明
`idToken`	集合	在 JWT ID 令牌中返回的可选声明。
`accessToken`	集合	在 JWT 访问令牌中返回的可选声明。
`saml2Token`	集合	在 SAML 令牌中返回的可选声明。

如果特定的声明支持这样做，则还可使用 additionalProperties 字段修改可选声明的行为。

名称	Type	说明
`name`	Edm.String	可选声明的名称。
`source`	Edm.String	声明的源（目录对象）。扩展属性提供预定义声明和用户定义的声明。如果源值为 null，则声明是预定义的可选声明。如果源值为 user，则 name 属性中的值是来自用户对象的扩展属性。
`essential`	Edm.Boolean	如果值为 true，则必须使用客户端指定的声明，以确保为最终用户请求的特定任务提供顺利的授权体验。默认值为 false。
`additionalProperties`	集合 (Edm.String)	声明的其他属性。如果此集合中存在某个属性，该属性将修改 name 属性中指定的可选声明的行为。

配置目录扩展可选声明

除了标准的可选声明集以外，还可将令牌配置为包含 Microsoft Graph 扩展。有关详细信息，请参阅使用扩展将自定义数据添加到资源。

重要

访问令牌始终使用资源清单而不是客户端生成。在请求 ...scope=https://graph.microsoft.com/user.read... 中，资源是 Microsoft Graph API。访问令牌是使用 Microsoft Graph API 清单（而不是客户端的清单）创建的。更改应用程序的清单永远不会导致 Microsoft Graph API 的令牌看上去不同。要验证 accessToken 更改是否有效，请为你的应用程序（而非其他应用）请求一个令牌。

可选声明支持扩展属性和目录扩展。在附加应用可使用的其他用户信息时，此功能非常有用。例如，用户已设置的其他标识符或重要配置选项。如果应用程序清单请求自定义扩展，而 MSA 用户登录到你的应用，则不会返回这些扩展。

目录扩展格式

使用应用程序清单配置目录扩展可选声明时，请使用扩展的完整名称（格式为：extension_<appid>_<attributename>）。 <appid> 是请求声明的应用程序的 appId（或客户端 ID）的剥离版本。

在 JWT 中，使用以下命名格式发出这些声明：extn.<attributename>。在 SAML 令牌中，使用以下 URI 格式发出这些声明：http://schemas.microsoft.com/identity/claims/extn.<attributename>

配置组可选声明

提示

本文中的步骤可能因开始使用的门户而略有不同。

本部分介绍可选声明下的配置选项，这些选项可将组声明中使用的组特性从默认的组 objectID 更改为从本地 Windows Active Directory 同步的特性。可以通过 Azure 门户或应用程序清单来配置组的可选声明。组可选声明仅在 JWT 中针对用户主体发出。服务主体不包含在 JWT 中发出的组可选声明中。

重要

对于 SAML 断言和 JWT，令牌中发出的组数分别被限制为 150 个和 200 个（包括嵌套组）。若要详细了解本地属性中组声明的组限制和重要注意事项，请参阅配置应用程序的组声明。

完成以下步骤，使用 Azure 门户配置组的可选声明：

选择要为其配置可选声明的应用程序。
在“管理”下，选择“令牌配置” 。
选择“添加组声明”。
选择要返回的组类型（“安全组”或“目录角色”、“所有组”和/或“分配给应用程序的组”）：
- “分配给应用程序的组”选项仅包括分配给应用程序的组。由于令牌中的组数限制，建议将“分配给应用程序的组”选项用于大型组织。若要更改分配给应用程序的组，请在“企业应用程序”列表中选择该应用程序。依次选择“用户和组”和“添加用户/组”。选择要从“用户和组”添加到应用程序的组。
- “所有组”选项包括“SecurityGroup”、“DirectoryRole”和“DistributionList”，但不包括“分配给应用程序的组” 。
可选：选择特定的令牌类型属性，将组声明值修改为包含本地组特性，或将声明类型更改为角色。
选择“保存”。

完成以下步骤，通过应用程序清单配置组可选声明：

选择要为其配置可选声明的应用程序。
在“管理”下，选择“清单” 。
使用清单编辑器添加以下条目：

有效值为：
- “所有”（此选项包括 SecurityGroup、DirectoryRole 和 DistributionList）
- "SecurityGroup"
- "DirectoryRole"
- “ApplicationGroup”（此选项仅包括分配给应用程序的组）
例如：
```
"groupMembershipClaims": "SecurityGroup"
```
默认情况下，将在组声明值中发出组对象 ID。若要修改声明值以包含本地组属性，或者要将声明类型更改为角色，请按如下所示使用 optionalClaims 配置：

设置组名配置可选声明。

如果你希望令牌中的组在“可选声明”部分包含本地组属性，请指定要将可选声明应用到哪个令牌类型。还可以指定所请求的可选声明的名称和所需的任何其他属性。

可以列出多个令牌类型：

idToken 表示 OIDC ID 令牌
accessToken 表示 OAuth 访问令牌
Saml2Token 表示 SAML 令牌。

Saml2Token 类型适用于 SAML1.1 和 SAML2.0 格式的令牌。

对于每个相关的令牌类型，请修改组声明以使用清单中的 optionalClaims 部分。 optionalClaims 架构如下所述：

{
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}

可选声明架构	值
`name`	必须是 `groups`
`source`	未使用。省略或指定 null。
`essential`	未使用。省略或指定 false。
`additionalProperties`	其他属性的列表。有效选项为 `sam_account_name`、`dns_domain_and_sam_account_name`、`netbios_domain_and_sam_account_name`、`emit_as_roles` 和 `cloud_displayname`。

在 additionalProperties 中，只需 sam_account_name、dns_domain_and_sam_account_name 和 netbios_domain_and_sam_account_name 中的一个。如果存在多个，则将使用第一个，而忽略其他。你还可以添加 cloud_displayname 来发出云组的显示名称。仅当 groupMembershipClaims 设置为 ApplicationGroup 时，此选项才起作用。

某些应用程序需要角色声明中有关用户的组信息。若要将声明类型从组声明更改为角色声明，请将 emit_as_roles 添加到 additionalProperties。组值在角色声明中发出。

如果使用了 emit_as_roles，则角色声明中不会显示任何已配置且分配给用户（或资源应用程序）的应用程序角色。

以下示例显示了组声明的清单配置：

在 OAuth 访问令牌中以 dnsDomainName\sAMAccountName 格式将组作为组名发出。

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

在 SAML 和 OIDC ID 令牌中以 netbiosDomain\sAMAccountName 格式将要返回的组名作为角色声明发出。

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

为本地同步组发出 sam_account_name 格式的组名称，为 SAML 中的云组发出 cloud_display 名称，为分配给应用程序的组发出 OIDC ID 令牌。

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

可选声明示例

可以使用多个选项来更新应用程序标识配置中的属性，以启用和配置可选声明：

可以使用 Azure 门户
可以使用清单。
也可以编写使用 Microsoft Graph API 的应用程序来更新应用程序。 Microsoft Graph API 参考指南中的 OptionalClaims 类型可帮助你配置可选声明。

在以下示例中，Azure 门户和清单用于向适用于应用程序的访问、ID 和 SAML 令牌添加可选声明。不同的可选声明添加到应用程序可以接收的每种令牌：

ID 令牌包含联合用户的完整格式 UPN (<upn>_<homedomain>#EXT#@<resourcedomain>)。
其他客户端为此应用程序请求的访问令牌包含 auth_time 声明。
SAML 令牌包含 skypeId 目录架构扩展（在本例中，此应用的应用 ID 为 ab603c56068041afb2f6832e2a17e237）。 SAML 令牌将 Skype ID 公开为 extension_ab603c56068041afb2f6832e2a17e237_skypeId。

在 Azure 门户中配置声明：

选择要为其配置可选声明的应用程序。
在“管理”下，选择“令牌配置” 。
选择“添加可选声明”，选择 ID 令牌类型，从声明列表中选择 upn，然后选择“添加” 。
选择“添加可选声明”，选择“访问”令牌类型，从声明列表中选择 auth_time，然后选择“添加” 。
在“令牌配置”概览屏幕中，选择 upn 旁边的铅笔图标，选择“外部身份验证”切换开关，然后选择“保存” 。
选择“添加可选声明”，选择“SAML”令牌类型，从声明列表中选择“extn.skypeID”（仅适用于已创建名为 skypeID 的 Microsoft Entra 用户对象的情况），然后选择“添加”。

在清单中配置声明：

选择要为其配置可选声明的应用程序。
在“管理”下，选择“清单”以打开内联清单编辑器。

可使用此编辑器直接编辑清单。该清单遵循 Application 实体的架构，保存后会自动设置格式。新元素添加到 optionalClaims 属性。

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

更新完清单后，选择“保存”以保存清单。

限制

一个应用程序最多可以将 10 个扩展属性作为可选声明发出。

通过

配置可选声明

先决条件

在应用程序中配置可选声明

配置目录扩展可选声明

目录扩展格式

配置组可选声明

可选声明示例

限制

反馈

其他资源

通过

配置可选声明

先决条件

在应用程序中配置可选声明

配置目录扩展可选声明

目录扩展格式

配置组可选声明

可选声明示例

限制

相关内容

反馈

其他资源