配置可选声明

可以通过 Azure 门户或应用程序清单来配置应用程序的可选声明。

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
2. 浏览到“标识”>“应用程序”>“应用注册”。
3. 请根据使用场景和期望的结果选择要为其配置可选声明的应用程序。
4. 在“管理”下，选择“令牌配置” 。
   • “标记配置”边栏选项卡的 UI 选项不适用于 Azure AD B2C 租户中注册的应用（可以通过修改应用程序清单来对其进行配置）。 有关更多信息，请参阅在 Azure Active Directory B2C 中使用自定义策略添加声明和自定义用户输入

使用清单配置声明：

1. 选择“添加可选声明”。

2. 选择要配置的令牌类型。

3. 选择要添加的可选声明。

4. 选择 添加 。

5. 在“管理”下，选择“清单” 。 此时会打开一个基于 Web 的清单编辑器，可在其中编辑清单。 （可选）可以选择“下载”并在本地编辑清单，然后使用“上传”将清单重新应用到应用程序。

   以下应用程序清单条目将 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
           }
       ]
   }
   

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

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 扩展。 有关详细信息，请参阅使用扩展将自定义数据添加到资源。

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

另请参阅

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

后续步骤

• 详细了解 Microsoft 标识平台中的令牌和声明。