Verwenden von MSAL Node mit dem nativen Tokenbroker (Windows)

Microsoft Authentication Library (MSAL) (MSAL) Node unterstützt das Anfordern von Tokens über den nativen Tokenbroker. Bei Verwendung des nativen Brokers sind Aktualisierungstoken an das Gerät gebunden, auf dem sie erworben werden und nicht von msal-node oder der Anwendung zugänglich sind. Dies bietet ein höheres Maß an Sicherheit, das allein durch msal-node nicht erreicht werden kann.

In diesem Artikel wird erläutert, wie Sie den Windows Broker konfigurieren, Besitznachweise einrichten und brokerspezifisches Verhalten verstehen.

Broker-Support ist auf den folgenden Plattformen verfügbar:

Was ist ein Broker?

Ein Authentifizierungsbroker ist eine Komponente, die auf dem Computer eines Benutzers ausgeführt wird und Authentifizierungs-Handshakes und Tokenlebenszyklus für verbundene Konten verwaltet. Auf Windows wird diese Rolle von Web Account Manager (WAM) ausgeführt. Die wichtigsten Vorteile umfassen Folgendes:

• Verbesserte Sicherheit. Sicherheitsverbesserungen werden über Betriebssystem- oder Brokerupdates bereitgestellt, ohne dass App-Codeänderungen erforderlich sind. Aktualisierungstoken sind gerätegebunden und vor Exfiltration geschützt.
• Unterstützte Funktionen Zugriff auf umfangreiche Betriebssystemfunktionen wie Windows Hello, Microsoft Entra Conditional Access-Richtlinien und FIDO-Sicherheitsschlüssel (Fast Identity Online) ohne zusätzlichen Gerüstcode.
• Systemintegration. Anwendungen schließen die integrierte Kontoauswahl ein, sodass Benutzer schnell ein vorhandenes Konto auswählen können, anstatt anmeldeinformationen erneut einzugeben.
• Tokenschutz. Der Broker stellt sicher, dass Refresh-Token gerätegebunden sind, und ermöglicht Apps, Proof-of-Possession-Zugriffstoken abzurufen.

Unterstützte Architekturen

• Windows: x64, x86, ARM64

Voraussetzungen

• Node.js 18 oder höher
• Installieren Sie @azure/msal-node-extensions als Abhängigkeit
• Registrieren Sie den Umleitungs-URI des Brokers bei Ihrer App-Registrierung. Den erforderlichen Wert finden Sie unter Umleitungs-URI.

Umleitungs-URI

Registrieren Sie den folgenden Umleitungs-URI unter der Plattform für Mobile und Desktopanwendungen im Azure-Portal:

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

Ersetzen Sie <your-client-id> durch die Client-ID Ihrer Anwendung.

Die Funktion aktivieren

Das Aktivieren der Tokenbrokerung erfordert nur einen Konfigurationsparameter. Übergeben Sie eine NativeBrokerPlugin Instanz in der Brokerkonfiguration:

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

Ein Arbeitsbeispiel finden Sie unter Beispiel „auth-code-cli-brokered-app sample”.

Fensterüberordnung

Damit Authentifizierungsaufforderungen über die aufrufende Anwendung angezeigt und weitere Interaktionen blockiert werden können, stellen Sie der API das Fensterhandle der acquireTokenInteractive Anwendung bereit.

Für CLI-Apps wird versucht, das Fensterhandle „hinter den Kulissen” zu finden, aber das ist nicht sehr zuverlässig.

Wenn Sie Electron verwenden, verwenden Sie die getNativeWindowHandle API, und übergeben Sie das Ergebnis an acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Proof of Possession (Besitznachweis)

Der Besitznachweis (PoP) für Zugriffstoken wird unterstützt, wenn Token über den nativen Broker abgerufen werden. Um ein PoP-Token anzufordern, fügen Sie dem Anforderungsobjekt, das an acquireTokenInteractive oder acquireTokenSilent übergeben wird, die folgenden Eigenschaften hinzu:

AT PoP-Anforderungsparameter

Verwendungsbeispiel

In diesem Beispiel wird ein Besitznachweistoken angefordert, indem das Authentifizierungsschema und die signierten HTTP-Anforderungseigenschaften festgelegt werden:

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

Unterschiede bei der Verwendung des Windows Brokers

Es gibt ein paar Dinge, die sich beim Abrufen von Token über den nativen Broker anders verhalten können:

• Der forceRefresh Parameter für acquireTokenSilent Aufrufe wird nicht unterstützt. Sie erhalten möglicherweise ein zwischengespeichertes Token vom Broker, unabhängig davon, wie dieses Flag festgelegt ist.
• Wenn der Broker den Benutzer zur Interaktion auffordern muss, wird eine Systemaufforderung geöffnet. Dadurch wird die Benutzeroberfläche (User Experience, UX) geändert, da die Authentifizierung nicht in einem Browserfenster auftritt.
• Der Zugriffstoken-Eigentumsnachweis wird vom Broker unterstützt, wird jedoch nicht vom Flow ohne Broker unterstützt.