Устранение проблем аутентификации в Azure Identity

В этой статье рассматриваются методы исследования сбоев, распространенные ошибки для типов учетных данных в клиентской библиотеке Java удостоверений Azure и действия по устранению этих ошибок. Так как многие типы учетных данных доступны в Azure SDK для 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 и сообщение: код ошибки и сообщение, возвращенные из Microsoft Entra STS, в этом случае AADSTS7000215: Invalid client secret provided. эта информация дает представление о конкретной причине, по которой запрос завершился сбоем. Например, в этом конкретном случае указанный секрет клиента является неверным. Дополнительные сведения о кодах ошибок STS см. в разделе «Коды ошибок AADSTS» в разделе «Коды ошибок идентификации и авторизации Microsoft Entra».

  • идентификатор корреляции и метка времени: идентификатор корреляции и метка времени вызова, используемая для идентификации запроса в журналах на стороне сервера. Эта информация полезна инженерам поддержки при диагностике непредвиденных сбоев STS.

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

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

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

Осторожность

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

Дальнейшие действия

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

  • Last updated on