Использование MSAL Node со встроенным брокером токенов (Windows)

Microsoft Authentication Library (MSAL) для Node.js поддерживает получение токенов через встроенный брокер токенов. При использовании нативного брокера токены обновления привязываются к устройству, на котором они были получены, и недоступны для msal-node или приложения. Это обеспечивает более высокий уровень безопасности, который не может быть достигнут только одним msal-node .

В этой статье объясняется, как настроить брокер Windows, настроить подтверждение владения и понять поведение брокера.

Поддержка брокера доступна на следующих платформах:

Platform Broker Documentation
Windows Менеджер веб-учетных записей (WAM) брокер Windows (эта статья)
macOS плагин Microsoft Enterprise SSO (Корпоративный портал) брокер для macOS
Linux Единый вход Microsoft для Linux Брокер Linux

Что такое брокер

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

  • Улучшенная безопасность. Улучшения безопасности предоставляются с помощью обновлений ОС или брокера, не требуя изменения кода приложения. Маркеры обновления привязаны к устройству и защищены от кражи.
  • Поддержка функций. Доступ к широким возможностям ОС, таким как Windows Hello, политики условного доступа Microsoft Entra и ключи безопасности Fast Identity Online (FIDO), без дополнительного вспомогательного кода.
  • Интеграция системы. Приложения интегрируются со встроенным средством выбора учетных записей, позволяя пользователям быстро выбрать существующую учетную запись вместо повторного ввода учетных данных.
  • Защита токенов. Брокер гарантирует, что маркеры обновления привязаны к устройству и позволяет приложениям получать маркеры доступа с подтверждением владения.

Поддерживаемые архитектуры

  • Windows: x64, x86, ARM64

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

  • Node.js 18 или новее
  • Установите @azure/msal-node-extensions как зависимость
  • Зарегистрируйте URI перенаправления брокера в регистрации приложения. Для требуемого значения см. URI перенаправления.

Перенаправляющий URI

Зарегистрируйте следующий URI перенаправления для платформы Мобильные и классические приложения в портале Azure:

ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>

Замените <your-client-id> идентификатором клиента приложения.

Включение функции

Чтобы включить посредничество с токенами, нужен всего один параметр конфигурации. Передайте экземпляр NativeBrokerPlugin в конфигурации брокера:

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

Note

msal-node не будет переключаться на неброкеризованный поток в случае сбоя. Включайте посреднический поток только в средах, которые его поддерживают, чтобы избежать неожиданных сбоев.

Рабочий пример можно найти в примере auth-code-cli-brokered-app.

Назначение родительского окна

Чтобы запросы аутентификации отображались поверх вызывающего приложения и блокировали дальнейшее взаимодействие, предоставьте API acquireTokenInteractive дескриптор окна приложения.

Для CLI-приложений на уровне реализации предпринимается попытка найти дескриптор окна, но этот механизм ненадёжен.

Если вы используете Electron, используйте getNativeWindowHandle API и передайте результат в acquireTokenInteractive:

import { BrowserWindow } from "electron";

const win = new BrowserWindow();
const pca = new PublicClientApplication(msalConfig);

pca.acquireTokenInteractive({
    windowHandle: win.getNativeWindowHandle(),
});

Подтверждение принадлежности

Подтверждение владения токеном доступа (PoP) поддерживается при получении токенов через встроенный брокер. Чтобы запросить токен PoP, добавьте следующие свойства в объект запроса, передаваемый в acquireTokenInteractive или acquireTokenSilent:

Параметры запроса AT PoP

Name Description Обязательный
authenticationScheme Указывает, следует ли MSAL получить токен Bearer или PoP. По умолчанию — Bearer. Required
resourceRequestMethod Полное имя метода HTTP запроса, который будет использовать подписанный токен (GET, , POSTPUTи т. д.) Required
resourceRequestUri URL-адрес защищенного ресурса, для которого выдан маркер доступа. Required
shrNonce Созданная сервером подписанная метка времени, представленная в виде строки в кодировке Base64URL. Это одноразовое значение (nonce) используется для снижения риска атак, связанных с рассинхронизацией часов и манипуляцией временем, направленных на то, чтобы сделать возможной предварительную генерацию токенов PoP. Необязательно

Пример использования

В этом примере запрашивается маркер подтверждения владения, задав схему проверки подлинности и подписанные свойства HTTP-запроса:

import { PublicClientApplication, Configuration, AuthenticationScheme } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

const popTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: AuthenticationScheme.POP,
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER",
};

pca.acquireTokenInteractive(popTokenRequest);
pca.acquireTokenSilent(popTokenRequest);

Note

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

Различия при использовании брокера Windows

Есть несколько аспектов, которые могут работать иначе при получении токенов через встроенный брокер:

  • Параметр forceRefresh для acquireTokenSilent вызовов не поддерживается. Вы можете получить кэшированный токен от брокера независимо от того, какое значение имеет этот флаг.
  • Если брокеру нужно запрашивать взаимодействие пользователя, откроется системный запрос. Это изменяет взаимодействие с пользователем (UX), так как проверка подлинности не происходит в окне браузера.
  • Подтверждение владения токеном доступа поддерживается брокером, но не поддерживается в неброкерном потоке.
  • Last updated on