Azure Identity plugin for brokered authentication

Этот пакет предоставляет плагин к библиотеке Azure Identity для JavaScript (@azure/identity), который позволяет использовать брокер аутентификации, например WAM.

Брокер проверки подлинности — это приложение, работающее на компьютере пользователя, которое управляет подтверждением проверки подлинности и обслуживанием маркеров для подключенных учетных записей. В настоящее время поддерживается только брокер проверка подлинности Windows — Web Account Manager (WAM).

Исходный код | Samples | API Reference Documentation | Microsoft Entra ID документация

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

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

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

• Подписка Azure.

Примечание: Для локальной разработки с помощью @azure/identity-broker, вам может потребоваться установка дополнительных инструментов. node-gyp используется для компиляции дополнений для доступа к системным API. Требования к установке перечислены в файле readme node-gyp.

В Linux библиотека используется libsecret , поэтому вам может потребоваться ее установка. В зависимости от вашего дистрибутива, вам нужно будет выполнить следующую команду:

• Debian/Ubuntu: sudo apt-get install libsecret-1-dev
• На базе Red Hat: sudo yum install libsecret-devel
• Арк Линукс: sudo pacman -S libsecret

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

Этот пакет предназначен для использования с Azure Identity for JavaScript. Установите @azure/identity и этот пакет с помощью npm:

npm install --save @azure/identity
npm install --save @azure/identity-broker

Поддерживаемые среды

Azure Плагины идентичности для JavaScript поддерживают стабильные (чётно нумерованые) версии Node.js, начиная с v20. Хотя подключаемые модули могут выполняться в других Node.js версиях, поддержка не гарантируется. @azure/identity-broker не поддерживает среды браузера.

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

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

Маркеры родительского окна

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

учетная запись Майкрософт (MSA) passthrough

Учетные записи Майкрософт (MSA) — это личные аккаунты, созданные пользователями для доступа к службы Майкрософт. Сквозное руководство MSA — это устаревшая конфигурация, которая позволяет пользователям получать маркеры к ресурсам, которые обычно не принимают имена входа MSA. Эта функция доступна только для сторонних приложений. Пользователи, прошедшие проверку подлинности с помощью приложения, настроенного для использования сквозного руководства MSA, могут задать legacyEnableMsaPassthrough для truetrue внутри , чтобы разрешить перечисление этих личных учетных записей WAM.

URI перенаправления

Приложения Microsoft Entra используют URI перенаправления, чтобы определить, куда отправить ответ на аутентификацию после входа пользователя. Чтобы включить проверку подлинности через WAM через брокер, URI перенаправления, соответствующий следующему шаблону, необходимо зарегистрировать в приложении:

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure Identity plugins

В @azure/identity версии 2.0.0 клиентская библиотека удостоверений для JavaScript включает API подключаемого модуля. Этот пакет (@azure/identity-broker) экспортирует объект подключаемого модуля, который необходимо передать в качестве аргумента функции useIdentityPlugin верхнего уровня из пакета @azure/identity. Включите собственный брокер в программе следующим образом:

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

После вызова useIdentityPluginподключаемый модуль собственного брокера регистрируется в пакете @azure/identity и будет доступен на InteractiveBrowserCredential, поддерживающей проверку подлинности брокера WAM. Эти учетные данные brokerOptions в параметрах конструктора.

Notes: Начиная с версии @azure/identity 4.11.0-beta.1, DefaultAzureCredential поддерживает вход через Windows Web Account Manager. Включите собственный брокер в программе следующим образом:

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

Примеры

После регистрации подключаемого модуля можно включить проверку подлинности посредника WAM, передав brokerOptions со свойством enabled, для параметра true конструктор учетных данных. В следующем примере мы используем InteractiveBrowserCredential.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

Полный пример использования приложения Electron для получения ручки окна см. этот образец.

Использование учетной записи по умолчанию для входа

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

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

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

См. руководство по диагностике различных сценариев отказа в Azure Identity устранение неполадок

Лесозаготовка

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

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

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

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

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