使用 Microsoft Graph 自定义声明策略（预览版）来自定义声明

项目
06/28/2024

“声明”是标识提供者在为某个用户颁发的令牌中陈述的有关该用户的信息。租户管理员使用声明自定义为其租户中的特定应用程序自定义令牌中发出的声明。声明自定义支持使用 SAML、OAuth 和 OpenID Connect 协议为应用程序配置声明。可以使用声明自定义来执行以下操作：

选择在令牌中包含的声明。
创建尚不存在的声明类型。
选择或更改在特定声明中发出的数据的源。

在本操作指南中，我们介绍了几种常见情况，以帮助你了解如何使用自定义声明策略。

先决条件

一个 Microsoft Entra 租户。
在 Microsoft Entra 管理中心配置的企业应用程序。
对于 PowerShell 用户，请下载最新的 Microsoft Graph PowerShell SDK。此步骤是可选的。

Microsoft Entra ID 中的声明自定义

Microsoft Entra ID 支持通过两种方式使用 Microsoft Graph/PowerShell 为应用程序自定义声明：

使用自定义声明策略（预览版）
使用声明映射策略

在以下示例中，我们为服务主体创建、更新和替换策略。自定义声明策略始终与服务主体对象相关联。在为应用程序/服务主体创建自定义声明策略之前，请确保已将企业应用程序配置为先决条件的一部分。

在浏览器中打开 Microsoft Graph 浏览器，至少以应用程序管理员的身份登录 Microsoft Graph 浏览器，然后选择以下方案之一。

省略令牌中的基本声明
在令牌中包括 EmployeeID 和 TenantCountry 作为声明
在令牌中使用声明转换

创建自定义声明策略后，应将应用程序配置为承认令牌包含自定义的声明。有关详细信息，请参阅安全注意事项。

省略令牌中的基本声明

在此示例中，我们创建一个自定义声明策略，该策略会从颁发给链接的服务主体的令牌中删除基本声明集。

在 Microsoft Graph 浏览器中，确定你要使用服务主体 API 为其配置自定义声明策略的应用程序。
通过运行以下 API 创建自定义声明策略。该策略与服务主体相链接，省略了来自令牌的基本声明。
```
PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy
```
请求正文：
```
{
    "includeBasicClaimSet": false
}
```

若要查看新策略，请运行以下命令

GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

响应：

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

在令牌中包含 `EmployeeID` 和 `TenantCountry` 以作为声明

在此示例中，我们创建针对声明的自定义，以将 EmployeeID 和 TenantCountry 添加到令牌中。在此示例中，我们还在令牌中包含基本声明集。

在 Microsoft Graph 浏览器中，确定你要使用服务主体 API 为其配置自定义声明策略的应用程序。

通过运行以下 API 创建自定义声明策略。此策略（链接到服务主体）向令牌添加 EmployeeID 和 TenantCountry 声明。

PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

请求正文：

{
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeid",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

若要查看新策略，请运行以下命令：

GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

响应：

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

在令牌中使用声明转换

在此示例中，我们更新一个策略，以便向颁发给链接的服务主体的 JWT 发出自定义声明“JoinedData”。此声明包含通过在用户对象的 extensionattribute1 属性中存储的数据后联接“-ext”后创建的值。在此示例中，我们在令牌中排除基本声明集。

在 Microsoft Graph 浏览器中，确定你要使用服务主体 API 为其配置自定义声明策略的应用程序。

通过运行以下 API 创建自定义声明策略。此策略向令牌发出自定义声明 JoinedData。

PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

请求正文：

{
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

注意

自定义声明策略是一种强类型策略，每个转换都使用不同的 @odata.type 值。

要查看新策略并获取策略 ObjectId，请运行以下命令：

GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

响应：

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

详细了解使用策略的声明自定义中的策略差异
Microsoft Graph 标识登录

通过

使用 Microsoft Graph 自定义声明策略（预览版）来自定义声明

先决条件

Microsoft Entra ID 中的声明自定义

省略令牌中的基本声明

在令牌中包含 `EmployeeID` 和 `TenantCountry` 以作为声明

在令牌中使用声明转换

反馈

其他资源

通过

使用 Microsoft Graph 自定义声明策略（预览版）来自定义声明

先决条件

Microsoft Entra ID 中的声明自定义

省略令牌中的基本声明

在令牌中包含 EmployeeID 和 TenantCountry 以作为声明

在令牌中使用声明转换

相关内容

反馈

其他资源

在令牌中包含 `EmployeeID` 和 `TenantCountry` 以作为声明