Устранение неполадок при проверке подлинности удостоверений Azure

Статья
10/23/2023

В этой статье рассматриваются методы исследования сбоев, распространенные ошибки для типов учетных данных в клиентской библиотеке Java удостоверений Azure и действия по устранению этих ошибок. Так как в пакете SDK Azure для Java доступно множество типов учетных данных, мы разделили руководство по устранению неполадок на разделы на основе сценария использования. Доступны следующие разделы.

В оставшейся части этой статьи рассматриваются общие методы устранения неполадок и рекомендации, применимые ко всем типам учетных данных.

Обработка исключений удостоверений Azure

Как отмечалось в разделе "Устранение неполадок " в разделе "Обработка исключений" в пакете SDK azure для Java, существует полный набор исключений и кодов ошибок, которые пакет SDK Azure для 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. Этот тип исключения используется для указания того, что учетные данные не могут пройти проверку подлинности в текущей среде из-за отсутствия требуемой конфигурации или установки. Это исключение также используется в качестве сигнала к цепочке типов учетных данных, таких как DefaultAzureCredential и ChainedTokenCredential, что учетные данные, связанные, должны продолжать пытаться использовать другие типы учетных данных позже в цепочке.

Проблемы с разрешениями.

Вызовы клиентов служб, HttpResponseExceptionStatusCode в результате чего 401 или 403 часто указывают, что вызывающий объект не имеет достаточных разрешений для указанного 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: код ошибки и сообщение, возвращенные из службы STS Microsoft Entra, в этом случае AADSTS7000215: Invalid client secret provided. эта информация может дать представление о конкретной причине, по которой запрос завершился сбоем. Например, в этом конкретном случае, так как предоставленный секрет клиента является неверным. Дополнительные сведения о кодах ошибок STS см. в разделе кодов ошибок AADSTS проверки подлинности и авторизации Microsoft Entra.
Идентификатор корреляции и метка времени: идентификатор корреляции и метка времени вызова, используемая для идентификации запроса в журналах на стороне сервера. Эта информация полезна для поддержки инженеров при диагностике непредвиденных сбоев stS.

Включение и настройка ведения журнала

Пакет SDK Azure для Java предлагает согласованную историю ведения журнала, чтобы помочь в устранении ошибок приложений и ускорить их разрешение. Журналы вызвали запись потока приложения, прежде чем достичь состояния терминала, чтобы помочь найти корневую проблему. Инструкции по ведению журнала см. в разделе "Настройка ведения журнала" в пакете SDK Azure для Java и устранении неполадок по просмотру.

Базовая библиотека MSAL, MSAL4J, также содержит подробное ведение журнала. Это ведение журнала очень подробно и включает все персональные данные, включая маркеры. Это ведение журнала наиболее полезно при работе с поддержкой продуктов. С версии 1.10.0 учетные данные, которые предлагают это ведение журнала, имеют метод enableUnsafeSupportLogging().

Внимание

Запросы и ответы в библиотеке удостоверений Azure содержат конфиденциальную информацию. Необходимо принять меры предосторожности для защиты журналов при настройке выходных данных, чтобы избежать ущерба безопасности учетной записи.

Следующие шаги

Если рекомендации по устранению неполадок, описанные в этой статье, не помогают устранить проблемы при использовании клиентских библиотек пакета SDK Azure для Java, рекомендуется отправить проблему в репозитории Azure SDK для Java GitHub.

Поделиться через