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

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

Как работает связанное удостоверение

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

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

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

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

Осведомленность о среде. Автоматически выбирает наиболее подходящие учетные данные в зависимости от среды, в которой выполняется приложение. Без этого вам потребуется написать код следующим образом:
```
import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new AzureCliCredential();
}
```
Плавный переход: Ваше приложение может перейти от локальной разработки к тестовой или рабочей среде без изменения кода аутентификации.
Улучшенная устойчивость. Включает резервный механизм, который переходит к следующим учетным данным, когда предыдущий не получает маркер доступа.

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

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

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

Обзор DefaultAzureCredential

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

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

Заказ	Подтверждение компетенции	Описание	Включено по умолчанию?
1	Окружающая среда	Считывает коллекцию переменных окружения, чтобы выяснить, настроен ли служебный принципал (пользователь приложения) для приложения. Если так, `DefaultAzureCredential` использует эти значения для проверки подлинности приложения в Azure. Этот метод чаще всего используется в средах сервера, но также может использоваться при разработке локально.	Да
2	Идентификация рабочей нагрузки	Если приложение развернуто на узле Azure с включенной рабочей идентификацией, выполните проверку подлинности этой учетной записи.	Да
3	Управляемая идентичность	Если приложение развернуто на узле Azure с включенным управляемым удостоверением, выполните проверку подлинности приложения в Azure с помощью этого управляемого удостоверения.	Да
4	Visual Studio Code	Если разработчик прошел проверку подлинности с помощью расширения ресурсов Azure в Visual Studio Code и установлен пакет @azure/identity-vscode , выполните проверку подлинности этой учетной записи.	Да
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	брокера	Выполняет проверку подлинности с помощью учетной записи по умолчанию, вошедшей в ОС через брокер. Требуется, чтобы установлен пакет @azure/identity-broker .	Да

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

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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

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

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

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

Схема цепочки DefaultAzureCredential с AZURE_TOKEN_CREDENTIALS, установленным на

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

Схема цепочки DefaultAzureCredential, где AZURE_TOKEN_CREDENTIALS установлены на 'dev', отображает исключительно учетные данные разработческих инструментов, включая Visual Studio Code, Azure CLI, Azure PowerShell, Azure Developer CLI и Broker.

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

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

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

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

AzureCliCredential
AzureDeveloperCliCredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Это важно

Переменная AZURE_TOKEN_CREDENTIALS среды поддерживает отдельные имена учетных данных в @azure/identity пакетах версии 4.11.0 и более поздних версий.

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

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Обзор ChainedTokenCredential

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

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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

Схема конфигурации ChainedTokenCredential, показывающая AzureCliCredential в качестве основного метода проверки подлинности с помощью VisualStudioCodeCredential в качестве дополнительного резервного варианта.

Подсказка

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

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

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

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

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

Отладка учетных данных

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

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

В предыдущем выводе следует отметить, что DefaultAzureCredential успешно получил токен с помощью AzureCliCredential.

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2025-10-10