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

Статья
02/13/2025

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

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

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

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

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

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

Осведомленность о среде. Автоматически выбирает наиболее подходящие учетные данные в зависимости от среды, в которой выполняется приложение. Без этого вам потребуется написать код следующим образом:
```
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 выполняется попытка учетных данных, следует.

Порядок	Подтверждение компетенции	Description	Включено по умолчанию?
1	Среда	Считывает коллекцию переменных среды, чтобы определить, настроен ли субъект-служба приложений (пользователь приложения) для приложения. В этом случае использует эти значения для `DefaultAzureCredential` проверки подлинности приложения в Azure. Этот метод чаще всего используется в средах сервера, но также может использоваться при разработке локально.	Да
2	Удостоверение рабочей нагрузки	Если приложение развернуто на узле Azure с включенным удостоверением рабочей нагрузки, выполните проверку подлинности этой учетной записи.	Да
3	управляемое удостоверение;	Если приложение развернуто на узле Azure с включенным управляемым удостоверением, выполните проверку подлинности приложения в Azure с помощью этого управляемого удостоверения.	Да
4	Visual Studio	Если разработчик прошел проверку подлинности в Azure, войдите в Visual Studio, выполните проверку подлинности приложения в Azure с помощью той же учетной записи.	Да
5	Azure CLI	Если разработчик прошел проверку подлинности в Azure с помощью команды Azure CLI `az login` , выполните проверку подлинности приложения в Azure с помощью той же учетной записи.	Да
6	Azure PowerShell	Если разработчик прошел проверку подлинности в Azure с помощью командлета `Connect-AzAccount` Azure PowerShell, выполните проверку подлинности приложения в Azure с помощью той же учетной записи.	Да
7	Интерфейс командной строки разработчика Azure	Если разработчик прошел проверку подлинности в Azure с помощью команды Azure Developer CLI `azd auth login` , выполните проверку подлинности с помощью этой учетной записи.	Да
8	Интерактивный браузер	Если этот параметр включен, в интерактивном режиме выполняется проверка подлинности разработчика через браузер по умолчанию текущей системы.	No

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

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

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

Совет

Метод UseCredential в приведенном выше фрагменте кода рекомендуется использовать в приложениях ASP.NET Core. Дополнительные сведения см. в статье "Использование пакета SDK Azure для .NET" в приложениях ASP.NET Core.

Настройка 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учетных данных. Измененная цепочка содержит только учетные данные во время разработки и выглядит следующим образом:

DefaultAzureCredential с помощью свойств Excludes

Примечание.

InteractiveBrowserCredential по умолчанию исключается и поэтому не отображается на предыдущей схеме. Чтобы включитьInteractiveBrowserCredential, передайте true конструктор DefaultAzureCredential(Boolean) или задайте для DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredentialсвойства false значение .

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

DefaultAzureCredential
ChainedTokenCredential

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

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

Обзор 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. В графической форме цепочка выглядит следующим образом:

ChainedTokenCredential

Совет

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

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

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

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

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

Поделиться через