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

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

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

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

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

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

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 — это специальный тип исключения, производный от ClientAuthenticationException. Этот тип исключения используется для указания того, что учетные данные не могут пройти проверку подлинности в текущей среде из-за отсутствия требуемой конфигурации или установки. Это исключение также используется в качестве сигнала к цепочке типов учетных данных, таких как DefaultAzureCredential и ChainedTokenCredential, что цепочка учетных данных должна продолжать проверять другие типы учетных данных позже в последовательности.

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

Вызовы к клиентам сервиса, приводящие к HttpResponseException с StatusCode 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, рекомендуется создать запрос в репозитории GitHub Azure SDK для Java.