Использование узла MSAL с брокером macOS

Microsoft Authentication Library (MSAL) Node может использовать брокер проверки подлинности macOS для предоставления единого входа (SSO) и получения безопасного токена с помощью учетных записей, известных операционной системе. В этой статье объясняется брокер macOS и как включить и использовать проверку подлинности с брокером в MSAL Node.

Обзор поддержки брокера на всех платформах см. в разделе Использование MSAL Node с собственным брокером токенов.

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

В системе macOS брокер аутентификации предоставляется плагином Microsoft Enterprise SSO для устройств Apple, который входит в состав приложения Корпоративный портал. Брокер управляет процедурами аутентификации и жизненным циклом токенов для подключенных учетных записей. В числе основных преимуществ можно назвать следующие:

• Улучшенная безопасность. Улучшения безопасности предоставляются через обновления брокера, не требуя изменения кода приложения. Маркеры обновления привязаны к устройству и защищены от кражи.
• Интеграция системы. Пользователи могут повторно использовать существующие учетные записи, в которые уже выполнен вход, из Корпоративный портал, что снижает необходимость повторного ввода учетных данных.
• Защита токенов. Брокер обеспечивает привязку маркеров обновления к контексту устройства.

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

Component	Поддерживается
Архитектура	ARM64 (Apple Silicon) и x64 (Intel)
версия macOS	macOS 10.15 (Catalina) и более поздних версий

Tip

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

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

• Node.js 18 или новее
• Установите @azure/msal-node-extensions как зависимость
• Устройство должно быть зарегистрировано через Корпоративный портал. После завершения регистрации убедитесь, что в других приложениях Microsoft можно выполнять вход через расширение единого входа (например, можно выполнить вход в Word через Корпоративный портал).
• Зарегистрируйте URI перенаправления брокера в регистрации вашего приложения. Поддерживаемые значения URI см. в разделе URI перенаправления.

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

Для потоков брокера macOS необходимо зарегистрировать URI перенаправления для платформы мобильных и классических приложений на портале Azure.

Для неподписанных приложений (скрипты, инструменты CLI):

Используйте следующий URI перенаправления для неподписанных приложений, таких как скрипты и средства CLI:

msauth.com.msauth.unsignedapp://auth

Для подписанных и пакетных приложений:

Используйте следующий формат URI перенаправления для подписанных или упакованных приложений:

msauth.<your-bundle-id>://auth

Замените <your-bundle-id> на идентификатор пакета Apple вашего приложения (например, msauth.com.example.myapp://auth).

Important

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

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

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

Получение токенов

Интерактивное получение токена

Используйте acquireTokenInteractive для запроса токена через брокер macOS:

const tokenRequest = {
    scopes: ["User.Read"],
};

const result = await pca.acquireTokenInteractive(tokenRequest);
console.log("Access token:", result.accessToken);

Получение токена без вмешательства пользователя

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

const accounts = await pca.getAllAccounts();

if (accounts.length > 0) {
    const silentRequest = {
        scopes: ["User.Read"],
        account: accounts[0],
    };

    const result = await pca.acquireTokenSilent(silentRequest);
    console.log("Access token (silent):", result.accessToken);
}

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

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

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

• Когда брокеру требуется взаимодействие с пользователем, появляется стандартное диалоговое окно аутентификации macOS. Это изменяет взаимодействие с пользователем (UX) по сравнению с проверкой подлинности на основе браузера.
• Параметр forceRefresh для acquireTokenSilent не поддерживается. Вы можете получить кэшированный маркер от брокера независимо от этого флага.
• Подтверждение владения токеном доступа (PoP) поддерживается через брокер.

Ограничения

• Источники аутентификации Azure AD B2C и службы федерации Active Directory (AD FS) (AD FS) не поддерживаются через брокер macOS.
• Сторонние поставщики удостоверений (IDP) не поддерживаются.
• Корпоративный портал необходимо установить, и устройство должно быть зарегистрировано для работы брокера.
• msal-node не возвращается в браузер, если брокер недоступен. Включите брокер только в средах, поддерживающих его.