排查自定义声明提供程序 API 的问题

项目
04/15/2024

身份验证事件和自定义声明提供程序支持通过与外部系统集成来自定义 Microsoft Entra 身份验证体验。例如，可以创建自定义声明提供程序 API，并将 OpenID Connect 应用或 SAML 应用配置为从外部存储接收包含声明的令牌。

错误行为

当 API 调用失败时，错误行为如下所示：

对于 OpenId Connect 应用 - Microsoft Entra ID 会将用户重定向回客户端应用程序，并显示错误。不会铸造令牌。
对于 SAML 应用 - Microsoft Entra ID 向用户显示身份验证体验中的错误屏幕。用户不会重定向回客户端应用程序。

发送回应用程序或用户的错误代码为泛型代码。若要进行故障排查，请检查错误代码的登录日志。

日志记录

若要排查自定义声明提供程序 REST API 终结点的问题，REST API 必须处理日志记录。 Azure Functions 和其他 API 开发平台提供深入的日志记录解决方案。使用这些解决方案获取有关 API 行为的详细信息，并排查 API 逻辑的问题。

提示

本文中的步骤可能因开始使用的门户而略有不同。

除了 REST API 日志和托管环境诊断解决方案之外，还可以使用 Microsoft Entra 登录日志。使用 Microsoft Entra 登录日志，可以找到可能影响用户登录的错误。Microsoft Entra 登录日志提供有关 Microsoft Entra ID 调用 API 时的 HTTP 状态、错误代码、执行持续时间和重试次数的信息。

Microsoft Entra 登录日志还与 Azure Monitor 集成。可以设置警报和监视、可视化数据，并与安全信息和事件管理 (SIEM) 工具集成。例如，如果错误数超过所选的特定阈值，则可以设置通知。

访问 Microsoft Entra 登录日志：

至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“企业应用程序”。
选择“登录日志”，然后选择最新的登录日志。
有关更多详细信息，请选择“身份验证事件”选项卡。此时将显示与自定义身份验证扩展 REST API 调用相关的信息，包括任何错误代码。

错误代码参考

使用下表诊断错误代码。

错误代码	错误名称	说明
1003000	EventHandlerUnexpectedError	处理事件处理程序时出现意外错误。
1003001	CustomExtenstionUnexpectedError	调用自定义扩展 API 时出现意外错误。
1003002	CustomExtensionInvalidHTTPStatus	自定义扩展 API 返回了无效的 HTTP 状态代码。检查 API 是否返回为该自定义扩展类型定义的接受状态代码。
1003003	CustomExtensionInvalidResponseBody	分析自定义扩展的响应正文时出现问题。检查 API 响应正文是否处于该自定义扩展类型的可接受架构中。
1003004	CustomExtensionThrottlingError	自定义扩展请求过多。达到限制时，自定义扩展 API 调用将引发此异常。
1003005	CustomExtensionTimedOut	自定义扩展在允许的超时时间内未响应。检查 API 是否在为自定义扩展配置的超时时间内响应。它还可能指示访问令牌无效。按照步骤直接调用 REST API。
1003006	CustomExtensionInvalidResponseContentType	自定义扩展的响应内容类型不是“application/json”。
1003007	CustomExtensionNullClaimsResponse	自定义扩展 API 使用了 null 声明包进行响应。
1003008	CustomExtensionInvalidResponseApiSchemaVersion	自定义扩展 API 未使用调用它来获取的同一 apiSchemaVersion 进行响应。
1003009	CustomExtensionEmptyResponse	自定义扩展 API 响应正文在未达到预期时为 null。
1003010	CustomExtensionInvalidNumberOfActions	自定义扩展 API 响应包含的操作数量与该自定义扩展类型支持的操作数量不同。
1003011	CustomExtensionNotFound	找不到与事件侦听器关联的自定义扩展。
1003012	CustomExtensionInvalidActionType	自定义扩展返回了为该自定义扩展类型定义的无效操作类型。
1003014	CustomExtensionIncorrectResourceIdFormat	自定义扩展的应用程序注册清单中的 identifierUris 属性的格式应为 api://{完全限定的域名}/{appid}。
1003015	CustomExtensionDomainNameDoesNotMatch	自定义扩展的 targetUrl 和 resourceId 应具有相同的完全限定域名。
1003016	CustomExtensionResourceServicePrincipalNotFound	自定义扩展 resourceId 的 appId 应对应于租户中的实际服务主体。
1003017	CustomExtensionClientServicePrincipalNotFound	在租户中找不到自定义扩展资源服务主体。
1003018	CustomExtensionClientServiceDisabled	此租户中禁用了自定义扩展资源服务主体。
1003019	CustomExtensionResourceServicePrincipalDisabled	此租户中禁用了自定义扩展资源服务主体。
1003020	CustomExtensionIncorrectTargetUrlFormat	目标 URL 的格式不正确。它必须是以 https 开头的有效 URL。
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	服务主体不具有适用于 Microsoft Graph CustomAuthenticationExtensions.Receive.Payload 应用角色（也称为应用程序权限）的管理员同意，而这是应用接收自定义身份验证扩展 HTTP 请求所必需的。
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	此租户中已禁用或找不到 MS Graph 服务主体。
1003023	CustomExtensionBlocked	服务阻止了用于自定义扩展的终结点。
1003024	CustomExtensionResponseSizeExceeded	自定义扩展响应大小超出了最大限制。
1003025	CustomExtensionResponseClaimsSizeExceeded	自定义扩展响应中声明的总大小超出了最大限制。
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	自定义扩展 API 使用包含 null 或空密钥的声明进行响应
1003027	CustomExtensionConnectionError	连接到自定义扩展 API 时出错。

直接调用 REST API

REST API 受 Microsoft Entra 访问令牌保护。可以通过以下方式测试 API；

使用与自定义身份验证扩展关联的应用程序注册获取访问令牌
使用 API 测试工具在本地测试 API。

获取访问令牌
API 测试工具

获取访问令牌后，向其传递 HTTP Authorization 标头。若要获取访问令牌，请执行以下步骤：

至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“应用程序注册”。
选择“Azure Functions 身份验证事件 API”应用注册（之前在配置令牌颁发事件的自定义声明提供程序中配置）。
复制应用程序 ID。
如果尚未创建应用机密，请执行以下步骤：
1. 选择“证书和机密”>“客户端密码”>“新建客户端密码”。
2. 添加客户端机密的说明。
3. 选择机密的过期时间，或指定自定义的生存期。
4. 选择“添加” 。
5. 请记下机密值，以便在客户端应用程序代码中使用。退出此页面后，此机密值永不再显示。
从菜单中选择“公开 API”，并复制“应用程序 ID URI”的值。例如 api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444。
打开首选的 API 测试工具并创建新的 HTTP 查询。
将“HTTP 方法”更改为 POST。

输入以下 URL。将 {tenantID} 替换为租户 ID。

https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

在“正文”下，选择“form-data”并添加以下键：

密钥	值
`grant_type`	`client_credentials`
`client_id`	应用程序的客户端 ID。
`client_secret`	应用程序的客户端密码。
`scope`	应用程序的应用程序 ID URI，然后添加 `.default`。例如： `api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default`

运行 HTTP 查询，并将 access_token 复制到 https://jwt.ms Web 应用中。
将 iss 与在 API 中配置的颁发者名称进行比较。
将 aud 与在 API 中配置的客户端 ID 进行比较。

若要使用首选的 API 测试工具直接测试 API，请执行以下步骤：

注意

如果使用了Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 包，请关闭令牌验证以进行测试。打开local.settings.json并添加以下参数

"AuthenticationEvents__BypassTokenValidation": true

完成测试后，请确保将其删除。

在 REST API 中，禁用 appid 或 azp声明验证。了解如何编辑之前创建的函数 API。
创建新的 HTTP 请求并将“HTTP 方法”设置为 POST。
在“正文”中，选择“原始”，然后选择“JSON”。

粘贴以下模拟 Microsoft Entra ID 发送到 REST API 的请求的 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 authentication extension ID>",
        "authenticationContext": {
            "correlationId": "<Enter correlation ID here>",
            "client": {
                "ip": "127.0.0.1",
                "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": "2023-08-16T00:00:00Z",
                "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": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

提示

如果正在使用从 Microsoft Entra ID 获取的访问令牌，请依次选择“授权”、“持有者令牌”，然后粘贴从 Microsoft Entra ID 收到的访问令牌。

选择“发送”，应收到如下所示的 JSON 响应：

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

常见性能改进

最常见的问题之一是自定义声明提供程序 API 在两秒的超时时间内没有响应。如果 REST API 在后续重试中未响应，则身份验证会失败。若要提高 REST API 的性能，请遵循以下建议：

如果 API 访问任何下游 API，请缓存用于调用这些 API 的访问令牌，因此不必在每次执行时获取新令牌。
性能问题通常与下游服务相关。添加日志记录，用于记录调用任何下游服务的处理时间。
如果使用云提供商托管 API，请使用托管计划保持 API 的热度。对于 Azure Functions，它可以是高级计划或专用计划。
运行自动集成测试以进行身份验证。还可使用 API 测试工具以仅测试 API 性能。

Share via