排查 Azure 标识身份验证的问题

项目
10/23/2023

本文介绍失败调查技术、Azure 标识 Java 客户端库中凭据类型的常见错误，以及解决这些错误的缓解步骤。由于 Azure SDK for Java 中提供了许多凭据类型，因此我们已根据使用方案将故障排除指南拆分为各部分。提供了以下部分：

本文的其余部分介绍了适用于所有凭据类型的常规故障排除技术和指南。

处理 Azure 标识异常

如故障排除概述的 Azure SDK for Java 部分中的异常处理中所述，Azure SDK for Java 可以引发的一组全面的异常和错误代码。具体而言，对于 Azure 标识，需要了解一些关键异常类型。

ClientAuthenticationException

向服务发出请求的任何服务客户端方法都可能会引发身份验证错误导致的异常。这些异常是可能的，因为令牌是在首次调用服务时从凭据请求的，对于需要刷新令牌的服务的任何后续请求。

为了将这些故障与服务客户端中的故障区分开来，Azure 标识类会引发 ClientAuthenticationException 详细信息，其中描述了异常消息中错误的来源和错误消息。根据应用程序的不同，这些错误可能或可能无法恢复。以下代码演示了捕获 ClientAuthenticationException示例：

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

CredentialUnavailableException

CredentialUnavailableException 是派生自 ClientAuthenticationException的特殊异常类型。此异常类型用于指示凭据由于缺少所需的配置或设置，无法在当前环境中进行身份验证。此异常还用作链式凭据类型的信号，例如DefaultAzureCredentialChainedTokenCredential，链式凭据应继续尝试链中的其他凭据类型。

权限问题

对具有 401 或 403 的服务客户端的HttpResponseExceptionStatusCode调用通常表示调用方对指定 API 没有足够的权限。检查服务文档以确定特定请求需要哪些角色。确保已对资源授予经过身份验证的用户或服务主体相应的角色。

在异常消息中查找相关信息

ClientAuthenticationException 当凭据进行身份验证时发生意外错误时，将引发。这些错误可能包括从向 Microsoft Entra 安全令牌服务（STS）发出的请求收到的错误，并且通常包含有助于诊断的信息。请考虑以下 ClientAuthenticationException 消息：

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

此错误消息包含以下信息：

失败的凭据类型：未能进行身份验证的凭据类型，在本例中为 ClientSecretCredential。此信息在诊断链接凭据类型（如 DefaultAzureCredential 或 ChainedTokenCredential）的问题时非常有用。
STS 错误代码和消息：从 Microsoft Entra STS 返回的错误代码和消息 - 在这种情况下， AADSTS7000215: Invalid client secret provided. 此信息可以深入了解请求失败的具体原因。例如，在此特定情况下，因为提供的客户端密码不正确。有关 STS 错误代码的详细信息，请参阅 Microsoft Entra 身份验证和授权错误代码的 AADSTS 错误代码部分。
相关 ID 和时间戳：用于在服务器端日志中标识请求的相关 ID 和调用时间戳。此信息有助于在诊断意外 STS 故障时支持工程师。

启用和配置日志记录

Azure SDK for Java 提供了一致的日志记录故事，可帮助排查应用程序错误并帮助加快解决速度。生成的日志会在到达终端状态之前捕获应用程序的流，以帮助查找根本问题。有关日志记录的指导，请参阅 Azure SDK for Java 中的日志记录和基于视图的故障排除。

基础 MSAL 库 MSAL4J 也具有详细的日志记录。此日志记录非常详细，包括所有个人数据，包括令牌。使用产品支持时，此日志记录最有用。从 v1.10.0 起，提供此日志记录的凭据具有一 enableUnsafeSupportLogging()个名为的方法。

注意

Azure 标识库中的请求和响应包含敏感信息。自定义输出时必须采取预防措施来保护日志，以避免损害帐户安全性。

后续步骤

如果本文中的故障排除指南在使用 Azure SDK for Java 客户端库时无法解决问题，建议在 Azure SDK for Java GitHub 存储库中提出问题。

通过