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

Библиотека Azure Identity предоставляет креденшалы — общедоступные классы, которые реализуют интерфейс 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 для IntelliJ, выполните проверку подлинности этой учетной записи.
5	Visual Studio Code	Если разработчик прошел проверку подлинности с помощью расширения ресурсов Azure Visual Studio Code, а пакет azure-identity-broker установлен, выполните проверку подлинности этой учетной записи.
6	Azure CLI	Если разработчик прошел проверку подлинности в Azure с помощью команды Azure CLI az login , выполните проверку подлинности приложения в Azure с помощью той же учетной записи.
7	Azure PowerShell	Если разработчик прошел проверку подлинности в Azure с помощью командлета Connect-AzAccount Azure PowerShell, выполните проверку подлинности приложения в Azure с помощью той же учетной записи.
8	Интерфейс командной строки разработчика 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();

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

Чтобы исключить все учетные данные, кроме одного, задайте для переменной AZURE_TOKEN_CREDENTIALS среды имя учетных данных. Например, можно уменьшить цепочку, установив для нее DefaultAzureCredential значение AzureCliCredentialAZURE_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 определенной реализацией TokenCredential, например ManagedIdentityCredential.

Для этого есть следующие причины.

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

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

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

Для примера предположим, что форма без параметров DefaultAzureCredential используется для аутентификации запроса к учетной записи Blob Storage. Приложение выполняется в локальной среде разработки, и разработчик прошел проверку подлинности в 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, последующие учетные данные не были проверены.