Клиентская библиотека удостоверений Azure для JavaScript версии 4.1.0

Библиотека удостоверений Azure предоставляет Microsoft Entra ID (ранее — Azure Active Directory) проверку подлинности с помощью набора удобных реализаций TokenCredential.

Примеры различных учетных данных см. на странице Примеры удостоверений Azure.

Основные ссылки:

• Исходный код
• Пакет (npm)
• Справочная документация по API
• документация по Microsoft Entra ID
• Примеры

Начало работы

Миграция с версии 1 на версию 2 @azure/identity

Если вы используете версию 1 , @azure/identityсм. руководство по миграции для обновления до версии 2.

Поддерживаемые в настоящее время среды

• LTS версии Node.js
  • Примечание: Если приложение работает на Node.js версии 8 или более поздней и вы не можете обновить Node.js версию до последней стабильной версии, закрепите @azure/identity зависимость до версии 1.1.0.
• Последние версии Safari, Chrome, Edge и Firefox.
  • Примечание. Среди различных учетных данных, экспортированных в эту библиотеку, это единственная, InteractiveBrowserCredential которая поддерживается в браузере.

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

Установка пакета

Установка удостоверения Azure с помощью npm:

npm install --save @azure/identity

Предварительные требования

• Подписка Azure.
• Необязательно. Azure CLI и (или) Azure PowerShell также могут быть полезны для проверки подлинности в среде разработки и управления ролями учетной записи.

Когда следует использовать @azure/identity

Классы учетных данных, предоставляемые службой @azure/identity , предназначены для предоставления наиболее простого способа проверки подлинности клиентов azure SDK локально, в средах разработки и в рабочей среде. Мы стремимся к простоте и разумной поддержке протоколов проверки подлинности, чтобы охватить большинство сценариев проверки подлинности, возможных в Azure. Мы активно расширяемся, чтобы охватить больше сценариев. Полный список предлагаемых учетных данных см. в разделе Классы учетных данных .

Все типы учетных данных, предоставляемые , @azure/identity поддерживаются в Node.js. Для браузеров — это тип учетных данных, InteractiveBrowserCredential используемый в сценариях обычной проверки подлинности.

Большинство типов учетных данных, предлагаемых в @azure/identity , используют библиотеку проверки подлинности Майкрософт для JavaScript (MSAL.js). В частности, мы используем библиотеки версии 2 MSAL.js, которые используют поток кода авторизации OAuth 2.0 с PKCE и совместимы с OpenID. Несмотря @azure/identity на простоту, библиотеки MSAL.js, такие как @azure/msal-common, @azure/msal-node и @azure/msal-browser, предназначены для обеспечения надежной поддержки протоколов проверки подлинности, поддерживаемых Azure.

Когда следует использовать что-то другое

@azure/identity Типы учетных данных являются реализациями класса @azure/core-authTokenCredential. В принципе, любой объект с методом getToken , удовлетворяющим getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> требованиям, будет работать как TokenCredential. Это означает, что разработчики могут создавать собственные типы учетных данных для поддержки вариантов проверки подлинности, не охваченных @azure/identity. Дополнительные сведения см. в статье Пользовательские учетные данные.

Хотя наши типы учетных данных поддерживают множество сложных вариантов, разработчикам может потребоваться полный контроль над протоколом проверки подлинности. В этом случае рекомендуется напрямую использовать библиотеку проверки подлинности Майкрософт для JavaScript (MSAL.js). Дополнительные сведения см. по следующим ссылкам:

• Мы рассмотрим некоторые расширенные варианты @azure/identity использования на странице Примеры удостоверений Azure .
  • В частности, у нас есть раздел Дополнительные примеры .
  • Кроме того, у нас есть раздел, в который показано, как выполнять проверку подлинности с помощью MSAL напрямую.

Для расширенных рабочих процессов проверки подлинности в браузере у нас есть раздел, в котором мы продемонстрируем, как напрямую использовать библиотеку @azure/msal-browser для проверки подлинности клиентов пакета SDK Azure.

Проверка подлинности клиента в среде разработки

Не смотря на то, что в рабочем приложении рекомендуется использовать управляемое удостоверение или проверку подлинности субъекта-службы, разработчик, как правило, для проверки подлинности вызовов служб Azure при отладке и локальном выполнении кода использует собственную учетную запись. Для выполнения этой проверки подлинности в среде разработки используются несколько средств разработчика.

Проверка подлинности с помощью Azure Developer CLI

Разработчики, программные за пределами интегрированной среды разработки, также могут использовать [Azure Developer CLI][azure_developer_cli] для проверки подлинности. Затем приложения, использующие DefaultAzureCredential или AzureDeveloperCliCredential, могут использовать эту учетную запись для проверки подлинности вызовов в своем приложении при локальном запуске.

Для проверки подлинности с помощью [Azure Developer CLI][azure_developer_cli] пользователи могут выполнить команду azd auth login. Для пользователей, работающих в системе с веб-браузером по умолчанию, Azure Developer CLI запустит браузер для проверки подлинности пользователя.

Для систем без веб-браузера по умолчанию команда azd auth login --use-device-code будет использовать поток проверки подлинности в коде устройства.

Проверка подлинности с помощью Azure CLI

Приложения, использующие AzureCliCredential, как напрямую, так и через DefaultAzureCredential, могут использовать учетную запись Azure CLI для проверки подлинности вызовов в приложении при локальном запуске.

Для проверки подлинности с помощью Azure CLI пользователи могут выполнить команду az login. Для пользователей, работающих в системе с веб-браузером по умолчанию, Azure CLI запустит браузер для проверки подлинности пользователя.

Для систем без веб-браузера по умолчанию команда az login будет использовать поток проверки подлинности в коде устройства. Кроме того, пользователь может заставить Azure CLI использовать поток кода устройства, а не запускать браузер с аргументом --use-device-code.

Проверка подлинности с помощью Azure PowerShell

Приложения, использующие AzurePowerShellCredential, как напрямую, так и через DefaultAzureCredential, могут использовать учетную запись, подключенную к Azure PowerShell, для проверки подлинности вызовов в приложении при локальном запуске.

Для проверки подлинности с помощью Azure PowerShell пользователи Connect-AzAccount могут запустить командлет . По умолчанию ike Azure CLI Connect-AzAccount запустит веб-браузер по умолчанию для проверки подлинности учетной записи пользователя.

Если интерактивная проверка подлинности не поддерживается в сеансе -UseDeviceAuthentication , аргумент будет принудительно использовать вместо командлета поток проверки подлинности кода устройства, аналогично соответствующему параметру в учетных данных Azure CLI.

Проверка подлинности с помощью Visual Studio Code

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

Для проверки подлинности в Visual Studio Code убедитесь, что установлено расширение учетной записи Azure. После установки откройте палитру команд и выполните команду Azure: Вход .

Кроме того, используйте пакет подключаемого @azure/identity-vscode модуля. Этот пакет предоставляет зависимости VisualStudioCodeCredential и включает его. См . раздел Подключаемые модули.

Это известная проблема , которая VisualStudioCodeCredential не работает с расширениями учетной записи Azure версии новее 0.9.11. В настоящее время выполняется долгосрочное решение этой проблемы. В то же время рассмотрите возможность проверки подлинности с помощью Azure CLI.

Проверка подлинности клиента в браузерах

Для проверки подлинности клиентов пакета SDK Azure в веб-браузерах мы предлагаем InteractiveBrowserCredential, который можно настроить для использования перенаправления или всплывающих окон для завершения потока проверки подлинности. Сначала необходимо создать регистрацию приложение Azure в портал Azure для веб-приложения.

Основные понятия

Если вы впервые используете @azure/identity или Microsoft Entra ID, сначала прочитайте статью Использование @azure/identity с Microsoft Entra ID. Этот документ содержит более глубокое представление о платформе и о том, как правильно настроить учетную запись Azure.

Учетные данные

Учетные данные представляет собой класс, который содержит или может получать данные, необходимые клиенту службы для аутентификации запросов. Клиенты служб в пакете AZURE SDK принимают учетные данные при их создании. Клиенты службы используют эти учетные данные для проверки подлинности запросов к службе.

Библиотека удостоверений Azure фокусируется на проверке подлинности OAuth с помощью Microsoft Entra ID и предлагает различные классы учетных данных, способные получить маркер Microsoft Entra для проверки подлинности запросов на обслуживание. Все классы учетных данных в этой библиотеке являются реализациями абстрактного класса TokenCredential, и любой класс может использоваться для создания клиентов службы, способных выполнить проверку подлинности с помощью класса TokenCredential.

См. статью Классы учетных данных.

DefaultAzureCredential

подходит DefaultAzureCredential для большинства сценариев, в которых приложение в конечном итоге должно быть запущено в Azure. Это связано с тем, что DefaultAzureCredential объединяет учетные данные, часто используемые для проверки подлинности при развертывании, с учетными данными, используемыми для проверки подлинности в среде разработки.

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

При использовании из Node.js DefaultAzureCredential будет пытаться пройти проверку подлинности с помощью следующих механизмов по порядку:

1. Среда — DefaultAzureCredential считывает сведения об учетной записи, указанные с помощью переменных среды, и использует их для проверки подлинности.
2. Удостоверение рабочей нагрузки. Если приложение развернуто в Служба Azure Kubernetes с включенным управляемым удостоверением, DefaultAzureCredential выполняет проверку подлинности с помощью него.
3. Управляемое удостоверение . Если приложение развернуто на узле Azure с включенным управляемым удостоверением DefaultAzureCredential , будет проходить проверку подлинности с помощью этой учетной записи.
4. Azure CLI . Если разработчик прошел проверку подлинности учетной записи с помощью команды Azure CLI az login , будет проходить проверку подлинности DefaultAzureCredential с помощью этой учетной записи.
5. Azure PowerShell . Если разработчик прошел проверку подлинности с помощью команды модуля Connect-AzAccount Azure PowerShell, DefaultAzureCredential будет проходить проверку подлинности с помощью этой учетной записи.
6. Azure Developer CLI . Если разработчик прошел проверку подлинности учетной записи с помощью команды Azure Developer CLIazd auth login, DefaultAzureCredential будет проходить проверку подлинности с помощью этой учетной записи.

Политика продолжения

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

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

Примечание о VisualStudioCodeCredential

Из-за известной проблемыVisualStudioCodeCredential удален из цепочки маркеровDefaultAzureCredential. Когда проблема будет устранена в будущем выпуске, это изменение будет отменено.

Подключаемые модули

Удостоверение Azure для JavaScript предоставляет API подключаемого модуля, который позволяет предоставлять определенные функциональные возможности с помощью отдельных пакетов подключаемых модулей. Пакет @azure/identity экспортирует функцию верхнего уровня (useIdentityPlugin), которую можно использовать для включения подключаемого модуля. Мы предоставляем два пакета подключаемых модулей:

• @azure/identity-broker, который обеспечивает поддержку проверки подлинности через собственный брокер, например диспетчер веб-учетных записей.
• @azure/identity-cache-persistence, который обеспечивает постоянное кэширование маркеров в Node.js с помощью собственной защищенной системы хранения, предоставляемой вашей операционной системой. Этот подключаемый модуль позволяет сохранять кэшированные access_token значения между сеансами, а это означает, что интерактивный поток входа не нужно повторять, пока доступен кэшированный маркер.

Примеры

Другие примеры использования различных учетных данных можно найти на странице "Примеры удостоверений Azure"

Проверка подлинности с помощью DefaultAzureCredential

В этом примере демонстрируется проверка подлинности KeyClient из клиентской библиотеки @azure/keyvault-keys с помощью DefaultAzureCredential.

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

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

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

Определение пользовательского потока проверки подлинности с помощью ChainedTokenCredential

Хотя DefaultAzureCredential, как правило, является самым быстрым способом приступить к разработке приложений для Azure, более опытным пользователям могут потребоваться настройки учетных данных, которые учитываются при проверке подлинности. ChainedTokenCredential позволяет пользователям объединять несколько экземпляров учетных данных для определения настраиваемой цепочки учетных данных. В этом примере показано создание ChainedTokenCredential объекта , который будет пытаться пройти проверку подлинности с помощью двух разных настроенных экземпляров ClientSecretCredential, чтобы затем выполнить проверку подлинности KeyClient из @azure/keyvault-keys:

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

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

Поддержка управляемых удостоверений

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

• Служба приложений Azure и Функции Azure
• Azure Arc
• Azure Cloud Shell;
• Служба Azure Kubernetes
• Azure Service Fabric
• Виртуальные машины Azure
• Масштабируемые наборы azure Виртуальные машины

Примеры использования управляемого удостоверения для проверки подлинности см. в примерах.

Конфигурация облака

Учетные данные по умолчанию — проверка подлинности в конечной точке Microsoft Entra для общедоступного облака Azure. Чтобы получить доступ к ресурсам в других облаках, таких как Azure для государственных организаций или частное облако, настройте учетные данные с помощью аргумента authorityHost в конструкторе. Интерфейс AzureAuthorityHosts определяет центры для известных облаков. Для облака для государственных организаций США можно создать экземпляр учетных данных следующим образом:

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

Не все учетные данные требуют такой конфигурации. Учетные данные, которые проходят проверку подлинности с помощью средства разработки, например AzureCliCredential, используют конфигурацию этого средства. Аналогичным образом принимает authorityHost аргумент, VisualStudioCodeCredential но по умолчанию использует соответствующий authorityHost параметр Azure: Облако Visual Studio Code.

Классы учетных данных

Проверка подлинности приложений, размещенных в Azure

Подтверждение компетенции	Использование	Пример
DefaultAzureCredential	Предоставляет упрощенный интерфейс проверки подлинности для быстрого начала разработки приложений, работающих в Azure.	Пример
ChainedTokenCredential	Позволяет пользователям определять пользовательские потоки проверки подлинности, состоящие из нескольких учетных данных.	Пример
EnvironmentCredential	Проверяет подлинность субъекта-службы или пользователя с помощью информации об учетных данных, указанной в переменных среды.	Пример
ManagedIdentityCredential	Проверяет подлинность управляемого удостоверения ресурса Azure.	Пример
WorkloadIdentityCredential	Поддерживает Идентификация рабочей нагрузки Microsoft Entra в Kubernetes.	Пример

Проверка подлинности субъектов-служб

Подтверждение компетенции	Использование	Пример	Ссылка
ClientAssertionCredential	Выполняет проверку подлинности субъекта-службы с помощью подписанного утверждения клиента.	Пример	Проверка подлинности субъекта-службы
ClientCertificateCredential	Проверяет подлинность субъекта-службы с помощью сертификата.	Пример	Проверка подлинности субъекта-службы
ClientSecretCredential	Проверяет подлинность субъекта-службы с помощью секрета.	Пример	Проверка подлинности субъекта-службы

Аутентификация пользователей

Подтверждение компетенции	Использование	Пример	Ссылка
AuthorizationCodeCredential	Выполняет проверку подлинности пользователя с помощью ранее полученного кода авторизации.	Пример	Код проверки подлинности OAuth2
DeviceCodeCredential	Интерактивно проверяет подлинность пользователя на устройстве с помощью ограниченного пользовательского интерфейса.	Пример	аутентификация с помощью кода устройства;
InteractiveBrowserCredential	Интерактивно проверяет подлинность пользователя с помощью системного браузера по умолчанию. Дополнительные сведения об этом процессе см. здесь.	Пример	Код проверки подлинности OAuth2
OnBehalfOfCredential	Распространяет удостоверение и разрешения делегированного пользователя через цепочку запросов.		Проверка подлинности от имени
UsernamePasswordCredential	Проверяет подлинность пользователя с помощью имени пользователя и пароля.	Пример	Проверка подлинности по имени пользователя и паролю

Проверка подлинности с помощью средств разработки

Подтверждение компетенции	Использование	Пример	Ссылка
AzureCliCredential	Проверка подлинности в среде разработки с помощью Azure CLI.	Пример	Проверка подлинности Azure CLI
AzureDeveloperCliCredential	Проверка подлинности в среде разработки с включенным пользователем или субъектом-службой в Azure Developer CLI.		Справочник по Azure Developer CLI
AzurePowerShellCredential	Проверка подлинности в среде разработки с помощью Azure PowerShell.	Пример	проверка подлинности Azure PowerShell
VisualStudioCodeCredential	Выполняет проверку подлинности как пользователь, вошедшего в расширение учетной записи Azure Visual Studio Code.		расширение VS Code для учетной записи Azure.

Переменные среды

DefaultAzureCredential и EnvironmentCredential можно настроить с помощью переменных среды. Для каждого типа проверки подлинности требуются значения для определенных переменных.

Субъект-служба с секретом

Имя переменной	Значение
AZURE_CLIENT_ID	Идентификатор приложения Microsoft Entra
AZURE_TENANT_ID	Идентификатор клиента Microsoft Entra приложения
AZURE_CLIENT_SECRET	Один из секретов клиента приложения

Субъект-служба с сертификатом

Имя переменной	Значение
AZURE_CLIENT_ID	Идентификатор приложения Microsoft Entra
AZURE_TENANT_ID	Идентификатор клиента Microsoft Entra приложения
AZURE_CLIENT_CERTIFICATE_PATH	путь к файлу сертификата в кодировке PEM, включая закрытый ключ
AZURE_CLIENT_CERTIFICATE_PASSWORD	пароль файла сертификата, если он есть

Имя пользователя и пароль

Имя переменной	Значение
AZURE_CLIENT_ID	Идентификатор приложения Microsoft Entra
AZURE_TENANT_ID	Идентификатор клиента Microsoft Entra приложения
AZURE_USERNAME	Имя пользователя (обычно это адрес электронной почты)
AZURE_PASSWORD	Пароль пользователя

Настройка выполняется в указанном порядке. Например, если заданы значения секрета клиента и сертификата, будет использоваться секрет клиента.

Непрерывная оценка доступа

Начиная с версии 3.3.0 доступ к ресурсам, защищенным с помощью непрерывной оценки доступа (CAE), возможен на основе каждого запроса. Это можно включить с помощью GetTokenOptions.enableCae(boolean) API. CAE не поддерживается для учетных данных разработчика.

Кэширование маркеров

Кэширование маркеров — это функция, предоставляемая библиотекой удостоверений Azure, которая позволяет приложениям:

• Кэшировать маркеры в памяти (по умолчанию) и на диске (согласие).
• Повышение устойчивости и производительности.
• Сократите количество запросов, выполняемых Microsoft Entra ID для получения маркеров доступа.

Библиотека удостоверений Azure предлагает кэширование как в памяти, так и постоянное кэширование дисков. Дополнительные сведения см. в документации по кэшированию маркеров.

Аутентификация через брокера

Брокер проверки подлинности — это приложение, которое выполняется на компьютере пользователя и управляет подтверждением проверки подлинности и обслуживанием маркеров для подключенных учетных записей. В настоящее время поддерживается только диспетчер веб-учетных записей Windows (WAM). Чтобы включить поддержку, используйте @azure/identity-broker пакет . Дополнительные сведения о проверке подлинности с помощью WAM см. в документации по подключаемого модулям брокера.

Устранение неполадок

Сведения об устранении неполадок см. в руководстве по устранению неполадок.

Дальнейшие действия

Читать документацию

Документацию по API для этой библиотеки можно найти на нашем сайте документации.

Поддержка клиентских библиотек

Клиентские библиотеки и библиотеки управления, перечисленные на странице выпусков azure SDK, которые поддерживают проверку подлинности Microsoft Entra, принимают учетные данные из этой библиотеки. Дополнительные сведения об использовании этих библиотек см. в документации, связанной со страницей выпусков.

Известные проблемы

Поддержка Azure AD B2C

Эта библиотека не поддерживает службу Azure AD B2C.

Другие открытые проблемы см. в репозитории GitHub библиотеки.

Предоставление отзыва

Если у вас возникли ошибки или есть предложения, откройте проблему.

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.