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

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

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

Ключевые ссылки:

• исходный код.
• Пакет (npm)
• Справочная документация по API
• Microsoft Entra Документация, удостоверяющая личность
• Примеры

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

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

• LTS версии Node.js
• Последние версии Safari, Chrome, Edge и Firefox.
  • примечание. Среди различных учетных данных, экспортированных в этой библиотеке, InteractiveBrowserCredential является единственным, поддерживаемым в браузере.

Дополнительные сведения см. вполитики поддержки .

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

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

npm install --save @azure/identity

Необходимые условия

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

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

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

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

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

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

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

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

• Разработчики, которым требуется полный контроль над протоколом проверки подлинности и его конфигурацией.
• Наши типы учетных данных предназначены для использования с клиентами пакета SDK Azure с интеллектуальным кэшированием и обновлением маркеров, обрабатываемых на базовом уровне HTTP. Если вам нужно использовать getToken напрямую, вы можете воспользоваться MSAL.js для более контроля над потоком проверки подлинности и кэшированием маркеров.

Дополнительные сведения см. по следующим ссылкам:

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

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

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

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

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

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

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

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

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

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

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

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

кода устройства учетной записи Azure CLI

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

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

Чтобы выполнить проверку подлинности с помощью Azure PowerShell, выполните командлет Connect-AzAccount. По умолчанию, например 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.

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

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

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

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

Верительные грамоты

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

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

См. разделклассов учетных данных .

DefaultAzureCredential

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

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

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

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

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

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

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

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

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

Примеры

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// 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";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// 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
const client = new KeyClient(vaultUrl, credentialChain);

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

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

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

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

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

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

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

В качестве альтернативы указанию аргумента authorityHost можно также задать переменную среды AZURE_AUTHORITY_HOST URL-адрес центра облака. Этот подход полезен при настройке нескольких учетных данных для проверки подлинности в одном облаке или при необходимости определения целевого облака.

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

Перечисление AzureAuthorityHosts определяет органы для хорошо известных облаков для удобства; Однако если центр для вашего облака не указан в AzureAuthorityHosts, можно передать любой допустимый URL-адрес центра в виде строкового аргумента. Например:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

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

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

Цепочки учетных данных

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ознакомьтесь с документацией

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

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

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

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

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

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

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

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

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

Способствует

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