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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор DefaultAzureCredential

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

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

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Настройка DefaultAzureCredential

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

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

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

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

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeAzureCliCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ManagedIdentityClientId = userAssignedClientId
    });

credential = new ChainedTokenCredential(
    new ManagedIdentityCredential(clientId: userAssignedClientId),
    new VisualStudioCredential());

Обзор ChainedTokenCredential

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new ManagedIdentityCredential(clientId: userAssignedClientId),
        new VisualStudioCredential()));
});

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

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

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

• Конкретная TokenCredential реализация, например ManagedIdentityCredential. См. список производных параметров.
• Реализация, оптимизированная ChainedTokenCredential для среды Azure, в которой выполняется приложение.

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

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

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

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

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

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