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

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

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

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

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

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

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

• версии 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, сосредоточены на том, чтобы обеспечить самый простой способ проверки подлинности клиентов Пакета 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) напрямую. Дополнительные сведения см. по следующим ссылкам:

• Мы изображаем некоторые расширенные варианты использования @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. Это связано с тем, что DefaultAzureCredential объединяет учетные данные, часто используемые для проверки подлинности при развертывании с учетными данными, используемыми для проверки подлинности в среде разработки.

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

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

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. cli разработчика Azure. Если разработчик прошел проверку подлинности учетной записи с помощью команды командной строки разработчика Azure azd auth login, 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.

// 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);

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

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

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

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

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

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