自定义声明提供程序参考

2025-05-25

在本使用指南中，您可以了解用于自定义声明提供程序事件的 REST API 架构和声明映射策略结构。

令牌颁发开始事件

借助自定义声明提供程序令牌颁发事件，你能够使用来自外部系统的信息扩充或自定义应用程序令牌。此信息不能作为用户配置文件的一部分存储在 Microsoft Entra 目录中。

组件概述

若要设置自定义扩展并将其与应用程序集成，需要连接多个组件。下图显示了配置点的高级视图，以及为实现自定义扩展而创建的关系。

你应该有一个公开可用的 REST API 终结点。在此图中，它由 Azure 函数表示。 REST API 生成自定义声明并将其返回到自定义扩展。它与 Microsoft Entra 应用程序注册相关联。
需要在 Microsoft Entra ID 中配置一个自定义扩展，该扩展配置为连接到你的 API。
你需要一个接收自定义令牌的应用程序。例如 https://jwt.ms，这是一个 Microsoft 拥有的 Web 应用程序，可显示令牌的解码内容。
必须使用https://jwt.ms将应用程序（如）注册到 Microsoft Entra ID。
必须在应用程序与自定义扩展之间创建关联。
可以选择使用身份验证提供程序来保护 Azure 函数，在本文中，我们将使用 Microsoft Entra ID。

REST API

REST API 终结点负责与下游服务进行交互。例如，包含要添加到令牌配置的属性的数据库、其他 REST API、LDAP 目录或任何其他存储。

REST API 向 Microsoft Entra ID 返回包含属性的 HTTP 响应。 REST API 返回的属性不会自动添加到令牌中。相反，必须为要包含在令牌中的任何属性配置应用程序的声明映射策略。在 Microsoft Entra ID 中，声明映射策略修改为特定应用程序颁发的令牌中发出的声明。

向 REST API 请求

若要为令牌颁发开始事件开发自己的 REST API，请使用以下 REST API 数据协定。架构描述用于设计请求和响应处理程序的协定。

Microsoft Entra ID 中的自定义扩展使用 JSON 有效负载对 REST API 进行 HTTP 调用。 JSON 有效负载包含用户配置文件数据、身份验证上下文属性以及有关用户想要登录的应用程序的信息。以下 JSON 中的 id 值是表示 Microsoft Entra 身份验证事件服务的 Microsoft 应用程序。 JSON 属性可用于通过 API 执行额外逻辑。

以下 HTTP 请求演示了 Microsoft Entra 如何调用您的 REST API。此 HTTP 请求可用于通过模拟来自 Microsoft Entra 的请求来调试 REST API。

POST https://your-api.com/endpoint

Content-Type: application/json

[Request payload]

以下 JSON 文档提供了请求有效负载的示例：

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", 
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

当 Fabrikam 组织的 B2B 用户向 Contoso 的组织进行身份验证时，发送到 REST API 的请求有效负载具有以下格式的 user 元素：

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

来自 REST API 的响应

Microsoft Entra ID 预期在以下 HTTP 中获得 REST API 响应。

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

在 HTTP 响应中，提供以下 JSON 文档，其中声明 DateOfBirth 并 CustomRoles 返回到 Microsoft Entra：

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

支持的数据类型

下表显示了自定义声明提供程序对于令牌颁发开始事件支持的数据类型：

数据类型	支持
字符串	真实
字符串数组	真实
布尔	假
JSON（JavaScript 对象表示法）	假

声明大小限制

声明提供程序可以返回的最大声明大小限制为 3KB。这是 REST API 返回的所有键和值对的总和。

声明映射策略

在 Microsoft Entra ID 中，声明映射策略修改为特定应用程序颁发的令牌中发出的声明。它包括来自自定义声明提供程序的声明，并将其颁发到令牌中。

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

元素 ClaimsSchema 包含要使用以下属性映射的声明列表：

Source 描述属性的源，即 CustomClaimsProvider。请注意，最后一个元素包含具有策略版本的固定值，以便进行测试。因此，将省略 source 属性。
ID 是从创建的 Azure 函数返回的声明名称。

重要

ID 属性的值区分大小写。请确保键入的声明名称与 Azure 函数返回的声明名称完全相同。
JwtClaimType 是 OpenID Connect 应用的发出令牌中声明的可选名称。它允许提供 JWT 令牌中返回的其他名称。例如，如果 API 响应的 ID 值为 dateOfBirth，则可以在令牌中作为 birthdate 发出。

创建声明映射策略后，下一步是将其上传到 Microsoft Entra 租户。在租户中使用以下 claimsMappingPolicy 图形 API。

重要

definition 元素应该是具有单个字符串值的数组。字符串应该是声明映射策略的字符串化和转义版本。可以使用 https://jsontostring.com/ 等工具将声明映射策略字符串化。

通过