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

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

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

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

Зачем использовать цепочки удостоверений

Цепные учетные данные могут предложить следующие преимущества:

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

  TokenCredential credential;
  
  if (app.Environment.IsProduction() || app.Environment.IsStaging())
  {
      credential = new ManagedIdentityCredential(
          ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
  }
  else
  {
      // local development environment
      credential = new VisualStudioCredential();
  }
  

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

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

Выбор связанных учетных данных

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

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

Обзор DefaultAzureCredential

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

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

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

DefaultAzureCredential credential = new();
BlobServiceClient client = new(
    new Uri($"https://{storageAccountName}.blob.core.windows.net"),
    credential);

Настройка DefaultAzureCredential

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

Исключение отдельной учетной записи

Чтобы исключить отдельные учетные данные из DefaultAzureCredential, используйте соответствующее свойство с префиксом Exclude в DefaultAzureCredentialOptions. Например:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

В предыдущем примере кода EnvironmentCredential, ManagedIdentityCredentialи WorkloadIdentityCredential удаляются из цепочки учетных данных. В результате первой учетной записью для попытки станет VisualStudioCredential. Измененная цепочка содержит только учетные данные во время разработки и выглядит следующим образом:

Так как больше Exclude-префиксированных свойств устанавливаются на true (настраиваются исключения учетных данных), преимущества использования DefaultAzureCredential уменьшаются. В таких случаях ChainedTokenCredential является более предпочтительным решением, так как это требует меньше кода. Чтобы проиллюстрировать, эти два примера кода ведут себя так же:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ExcludeBrokerCredential = true,
    });

credential = new ChainedTokenCredential(
    new VisualStudioCredential(),
    new AzureCliCredential());

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

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

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

Чтобы убедиться, что переменная среды определена и задана значением поддерживаемой строки, используйте перегрузку конструктора DefaultAzureCredential(String, DefaultAzureCredentialOptions).

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

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

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• BrokerCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• VisualStudioCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Чтобы убедиться, что переменная среды определена и задана значением поддерживаемой строки, используйте перегрузку конструктора DefaultAzureCredential(String, DefaultAzureCredentialOptions).

Обзор ChainedTokenCredential

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

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

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

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

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

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

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

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

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Для иллюстрации предположим, что для проверки подлинности запроса в рабочую область Log Analytics был использован DefaultAzureCredential без параметров. Приложение запущено в локальной среде разработки, и Visual Studio прошел проверку подлинности в учетной записи Azure. При следующем запуске приложения в выходных данных появились следующие соответствующие записи:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

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

• EnvironmentCredential, WorkloadIdentityCredential, и ManagedIdentityCredential каждый не смог получить токен доступа Microsoft Entra в этом порядке.
• Запись с префиксом DefaultAzureCredential credential selected: указывает на учетные данные, которые были выбраны — VisualStudioCredential в данном случае. После успешного выполнения VisualStudioCredential дальнейшие учетные данные не использовались.