自定义声明提供程序参考

项目
07/29/2024

在此参考文章中，可以了解自定义声明提供程序事件的 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 执行额外逻辑。对 API 的请求采用以下格式：

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

{
    "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", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Azure 预期的 REST API 响应应采用以下格式，其中声明 DateOfBirth 和 CustomRoles 将返回到 Azure：

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

当 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"
}

支持的数据类型

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

数据类型	支持
字符串	True
字符串数组	True
布尔	False
JSON	False

声明大小限制

声明提供程序可以返回的最大声明大小限制为 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/ 等工具将声明映射策略字符串化。

通过