Цепочки учетных данных в библиотеке удостоверений Azure для Java

Библиотека удостоверений Azure предоставляет credentials — открытые классы, реализующие интерфейс TokenCredential библиотеки Azure Core. Учетные данные представляют собой отдельный поток проверки подлинности для получения маркера доступа из Microsoft Entra ID. Эти учетные данные можно объединить в цепочку, чтобы сформировать упорядоченную последовательность механизмов проверки подлинности, которые необходимо предпринять.

Как работает цепочка учетных данных

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

Почему следует использовать цепочки учетных данных

Учетные данные, связанные в цепочку, могут предложить следующие преимущества:

• Осведомленность о среде. Автоматически выбирает наиболее подходящие учетные данные в зависимости от среды, в которой выполняется приложение. Без этого вам потребуется написать код следующим образом:

  import com.azure.core.credential.TokenCredential;
  import com.azure.identity.AzureCliCredentialBuilder;
  import com.azure.identity.ManagedIdentityCredentialBuilder;
  
  // Code omitted for brevity
  
  TokenCredential credential = null;
  
  // Set up credential based on environment (Azure or local development)
  String environment = System.getenv("ENV");
  
  if (environment != null && environment.equals("production")) {
      credential = new ManagedIdentityCredentialBuilder()
          .clientId(userAssignedClientId)
          .build();
  } else {
      credential = new AzureCliCredentialBuilder()
          .build();
  }
  

• Простой переход. Ваше приложение может перейти от локальной разработки к промежуточной или рабочей среде без изменения кода проверки подлинности.

• Улучшенная устойчивость. Включает резервный механизм, который переходит к следующим учетным данным, когда предыдущий не получает маркер доступа.

Как выбрать цепочные учетные данные

Существует два различных подхода к цепочке обработки учетных данных:

• Используйте предварительно настроенную цепочку: начните с предварительно заданной цепочки, которая соответствует наиболее распространенным сценариям проверки подлинности. Для этого подхода см. раздел " Общие сведения о DefaultAzureCredential".
• "Создать" цепочку: начните с пустой цепочки и включите только то, что вам нужно. Для этого подхода см. раздел " Обзор ChainedTokenCredential ".

Обзор DefaultAzureCredential

DefaultAzureCredential — это настроенная на основе предпочтений предварительно настроенная цепочка учетных данных. Она предназначена для поддержки многих сред, а также наиболее распространенных потоков проверки подлинности и средств разработчика. В графической форме базовая цепочка выглядит следующим образом:

Порядок, в котором DefaultAzureCredential пытается использовать учетные данные, следующий.

Заказ	Подтверждение компетенции	Описание
1	Среда	Считывает коллекцию переменных окружения, чтобы определить, настроена ли учетная запись службы приложения (пользователь приложения) для этого приложения. В этом случае DefaultAzureCredential использует эти значения для проверки подлинности приложения в Azure. Этот метод можно использовать при разработке локально, но чаще всего используется в средах сервера.
2	Идентичность рабочей нагрузки	Если приложение развернуто на узле Azure с включенной функцией удостоверения рабочей нагрузки, аутентифицируйте эту учетную запись.
3	Управляемая идентичность	Если приложение развертывается на узле Azure с включенным управляемым удостоверением, выполните проверку подлинности приложения в Azure с помощью этого управляемого удостоверения.
4	IntelliJ	Если разработчик прошел проверку подлинности через Azure Toolkit for IntelliJ, выполните проверку подлинности этой учетной записи.
5	Visual Studio Code	Если разработчик прошел проверку подлинности с помощью расширения Azure Resources в Visual Studio Code и установлен пакет azure-identity-broker, выполните аутентификацию этой учетной записи.
6	Azure CLI	Если разработчик прошел проверку подлинности в Azure с помощью команды az login Azure CLI, выполните проверку подлинности приложения для Azure с помощью той же учетной записи.
7	Azure PowerShell	Если разработчик аутентифицировался в Azure с помощью командлета Connect-AzAccount Azure PowerShell, аутентифицируйте приложение в Azure используя ту же учетную запись.
8	CLI разработчика Azure	Если разработчик прошел проверку подлинности в Azure с помощью команды Azure Developer CLI azd auth login, аутентифицируйтесь с использованием этой учетной записи.
9	Брокер	Выполняет проверку подлинности с помощью учетной записи по умолчанию, вошедшей в ОС через брокер. Требует, чтобы пакет azure-identity-broker был установлен, так как используется инстанция с поддержкой брокера InteractiveBrowserCredential.

В самой простой форме можно использовать версию DefaultAzureCredential без параметров следующим образом:

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

Как настроить DefaultAzureCredential

В следующих разделах описываются стратегии контроля того, какие учетные данные включаются в цепочку.

Исключить категорию типа учетных данных

Чтобы исключить все Developer tool или Deployed service учетные данные, установите значение переменной среды AZURE_TOKEN_CREDENTIALS на prod или dev, соответственно. Если используется значение prod, основная цепочка учетных данных выглядит следующим образом:

Если используется значение dev , цепочка выглядит следующим образом:

Это важно

Переменная AZURE_TOKEN_CREDENTIALS среды поддерживается в azure-identity пакетах версии 1.16.1 и более поздних версий.

Чтобы убедиться, что переменная среды определена и установлена в поддерживаемое значение строкового типа, вызовите метод requireEnvVars следующим образом:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Это важно

Метод requireEnvVars доступен в azure-identity пакетах версии 1.18.0 и более поздних версий.

Чтобы использовать имя пользовательской переменной среды вместо значения по умолчанию, используйте AZURE_TOKEN_CREDENTIALS для создания ссылки на настраиваемую переменнуюAzureIdentityEnvVars.fromString():

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Замечание

Метод requireEnvVars вызывает исключение IllegalStateException, если указанные переменные среды не заданы или пусты.

Использование определенных учетных данных

Чтобы исключить все учетные данные, кроме одного, задайте для переменной AZURE_TOKEN_CREDENTIALS среды имя учетных данных. Например, вы можете сократить DefaultAzureCredential цепочку до AzureCliCredential, установив AZURE_TOKEN_CREDENTIALS в AzureCliCredential. Сравнение строк выполняется в нечувствительном к регистру режиме. Допустимые строковые значения для переменной среды:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Это важно

Переменная среды AZURE_TOKEN_CREDENTIALS поддерживает отдельные имена учетных данных в пакетах azure-identity версии 1.17.0 и более новых.

Чтобы убедиться, что переменная среды определена и задана в поддерживаемую строку, метод вызова требуетEnvVars следующим образом:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Обзор ChainedTokenCredential

ChainedTokenCredential — это пустая цепочка, в которую добавляются учетные данные в соответствии с потребностями приложения. Например:

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

В приведенном примере кода создается специализированная цепочка учетных данных, состоящая из двух учетных данных для разработки. Сначала предпринимается попытка с использованием AzureCliCredential, а затем IntelliJCredential, если это необходимо. В графической форме цепочка выглядит следующим образом:

Совет

Для повышения производительности оптимизируйте порядок учетных данных в ChainedTokenCredential от большинства до наименее используемых учетных данных.

Руководство по использованию по DefaultAzureCredential

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

DefaultAzureCredential предлагает ключевое преимущество: он отделяет код приложения от определенных механизмов проверки подлинности, что позволяет изменять конфигурацию проверки подлинности без изменения кода. Для опытных разработчиков, которые сознательно настраивают свою рабочую проверку подлинности, эта гибкость может быть полезной. Однако эта гибкость связана с потенциальными недостатками:

• Проблемы отладки: При ошибке проверки подлинности может быть сложно выполнить отладку и идентификацию проблемных учетных данных. Необходимо включить ведение журнала, чтобы отслеживать процесс от одного учетного данных к следующему и статус успешности или сбоя каждого. Дополнительные сведения см. в разделе Отладка цепочки учетных данных.
• Потери производительности: Процесс последовательной проверки нескольких учетных данных может привести к перегрузке производительности. Например, управляемая идентификация недоступна, когда вы запускаете программу на локальной машине для разработки. Следовательно, ManagedIdentityCredential всегда терпит сбой в локальной среде.
• Непредсказуемое поведение: DefaultAzureCredential проверяет наличие определенных переменных среды. Возможно, кто-то может добавить или изменить эти переменные среды на уровне системы на хост-компьютере. Эти изменения применяются глобально и, следовательно, изменяют поведение DefaultAzureCredential среды выполнения в любом приложении, работающем на этом компьютере.
• Несоответствие разрешений: DefaultAzureCredential останавливается на первых учетных данных, которые успешно получают токен, независимо от того, имеют ли эти учетные данные правильные разрешения. Например, учетные данные локальной разработки могут иметь более широкие разрешения, чем у управляемого удостоверения рабочей среды, что приводит к локальной работе приложения, но сбой проверок авторизации после развертывания.

Отладка цепочки учетных данных

Чтобы диагностировать непредвиденные проблемы или понять, что делает цепочка учетных данных, в приложении включите ведение журнала.

В целях иллюстрации предположим, что для аутентификации запроса к аккаунту Blob Storage используется форма без параметров DefaultAzureCredential. Приложение выполняется в локальной среде разработки, а разработчик аутентифицировался в Azure, используя Azure CLI. При запуске приложения в выходных данных отображаются следующие соответствующие записи:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

В предыдущих выходных данных обратите внимание, что:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential и VisualStudioCodeCredential не удалось каждому из них получить токен доступа Microsoft Entra в указанном порядке.
• Вызов AzureCliCredential.getToken завершается успешно, как указано в записи с суффиксом returns a token. После успешного выполнения AzureCliCredential, последующие учетные данные не были проверены.