MSAL Node gebruiken met de Native Token Broker (Windows)

Microsoft Authentication Library -knooppunt (MSAL) ondersteunt het verkrijgen van tokens van de systeemeigen tokenbroker. Wanneer u de natieve broker gebruikt, zijn verversingstokens gekoppeld aan het apparaat waarop ze zijn verkregen en zijn ze niet toegankelijk voor msal-node of de toepassing. Dit biedt een hoger beveiligingsniveau dat met msal-node alleen niet kan worden bereikt.

In dit artikel wordt uitgelegd hoe u de Windows broker configureert, bewijs van bezit instelt en inzicht geeft in het brokerspecifieke gedrag.

Broker-ondersteuning is beschikbaar op de volgende platforms:

Wat is een broker?

Een verificatiebroker is een onderdeel dat wordt uitgevoerd op de computer van een gebruiker en die de verificatiehanddruk- en tokenlevenscyclus voor verbonden accounts beheert. Op Windows wordt deze rol uitgevoerd door Web Account Manager (WAM). Belangrijke voordelen zijn onder andere:

• Verbeterde beveiliging. Beveiligingsverbeteringen worden geleverd via besturingssysteem- of broker-updates zonder dat er app-codewijzigingen nodig zijn. Refresh-tokens zijn apparaatgebonden en beschermd tegen gegevensdiefstal.
• Functieondersteuning. Toegang tot uitgebreide besturingssysteemmogelijkheden, zoals Windows Hello, Microsoft Entra Voorwaardelijke toegang-beleid en FIDO-beveiligingssleutels (Fast Identity Online) zonder extra scaffolding-code.
• Systeemintegratie. Toepassingen worden aangesloten op de ingebouwde accountkiezer, zodat gebruikers snel een bestaand account kunnen selecteren in plaats van referenties opnieuw in te voeren.
• Tokenbeveiliging. De broker zorgt ervoor dat vernieuwingstokens apparaatgebonden zijn en stelt apps in staat om toegangstokens voor bewijs van eigendom te verkrijgen.

Ondersteunde architecturen

• Windows: x64, x86, ARM64

Prerequisites

• Node.js 18 of hoger
• Installeer @azure/msal-node-extensions als afhankelijkheid
• Registreer de omleidings-URI van de broker bij de registratie van uw app. Zie Omleidings-URI voor de vereiste waarde.

Omleidings-URL

Registreer de volgende omleidings-URI onder het platform voor mobiele toepassingen en desktoptoepassingen in de Azure-portal:

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

Vervang door <your-client-id> de client-id van uw toepassing.

De functie inschakelen

Voor het inschakelen van tokenbrokering is slechts één configuratieparameter vereist. Geef een NativeBrokerPlugin exemplaar door in de brokerconfiguratie:

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

Een werkend voorbeeld vindt u in het voorbeeld auth-code-cli-brokered-app.

Vensterhiërarchie

Als u verificatieprompts wilt weergeven via de aanroepende toepassing en verdere interactie wilt blokkeren, geeft u de venstergreep van de toepassing aan de acquireTokenInteractive API.

Voor CLI-apps wordt er achter de schermen zo goed mogelijk geprobeerd de venster-handle te vinden, maar dat is onbetrouwbaar.

Als u Electron gebruikt, gebruikt u de getNativeWindowHandle API en geeft u het resultaat door aan acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Bewijs van bezit

Bewijs van bezit (PoP) voor toegangstokens wordt ondersteund bij het ophalen van tokens via de native broker. Als u een PoP-token wilt aanvragen, voegt u de volgende eigenschappen toe aan het aanvraagobject dat is verstrekt aan acquireTokenInteractive of acquireTokenSilent:

AT PoP-aanvraagparameters

Gebruiksvoorbeeld

In dit voorbeeld wordt een proof-of-possession-token aangevraagd door het verificatieschema en ondertekende EIGENSCHAPPEN van HTTP-aanvragen in te stellen:

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

Verschillen bij het gebruik van de Windows broker

Er zijn enkele dingen die zich mogelijk anders gedragen bij het verkrijgen van tokens via de systeemeigen broker:

• De forceRefresh parameter voor acquireTokenSilent aanroepen wordt niet ondersteund. Mogelijk ontvangt u een token uit de cache van de broker, ongeacht hoe deze vlag is ingesteld.
• Als de broker de gebruiker om interactie moet vragen, wordt er een systeemprompt geopend. Hierdoor wordt de gebruikerservaring (UX) gewijzigd omdat verificatie niet plaatsvindt in een browservenster.
• Het bewijs van eigendom van het toegangstoken wordt ondersteund door de broker, maar wordt niet ondersteund door de niet-broker-stroom.