配置可选声明

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

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

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

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

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

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

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

可选声明支持扩展属性和目录扩展。 在附加应用可使用的其他用户信息时，此功能非常有用。 例如，用户已设置的其他标识符或重要配置选项。 如果应用程序清单请求自定义扩展，而 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 中发出的组可选声明中。

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

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

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

1. 选择要为其配置可选声明的应用程序。

2. 在“管理”下，选择“清单” 。

3. 使用清单编辑器添加以下条目：

   有效值为：

   • “所有”（此选项包括 SecurityGroup、DirectoryRole 和 DistributionList）
   • "SecurityGroup"
   • "DirectoryRole"
   • “ApplicationGroup”（此选项仅包括分配给应用程序的组）

   例如：

   "groupMembershipClaims": "SecurityGroup"
   

   默认情况下，将在组声明值中发出组对象 ID。 若要修改声明值以包含本地组属性，或者要将声明类型更改为角色，请按如下所示使用 optionalClaims 配置：

4. 设置组名配置可选声明。

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

   可以列出多个令牌类型：

   • 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 门户中配置声明：

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

在清单中配置声明：

1. 选择要为其配置可选声明的应用程序。

2. 在“管理”下，选择“清单”以打开内联清单编辑器。

3. 可使用此编辑器直接编辑清单。 该清单遵循 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
           }
       ]
   }
   

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

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

• 访问令牌
• 应用程序清单
• ID 令牌
• 可选声明参考