Použití uzlu MSAL s nativním zprostředkovatelem tokenů (Windows)

Knihovna Identity a ověřování Microsoftu (MSAL) pro Node podporuje získávání tokenů z nativního zprostředkovatele tokenů. Při použití nativního zprostředkovatele jsou obnovovací tokeny vázané na zařízení, na kterém jsou získány, a nejsou přístupné aplikací msal-node . To poskytuje vyšší úroveň zabezpečení, které nelze dosáhnout pouze pomocí msal-node.

Tento článek vysvětluje, jak nakonfigurovat Windows zprostředkovatele, nastavit důkaz o vlastnictví a pochopit chování specifické pro zprostředkovatele.

Podpora zprostředkovatele je dostupná na následujících platformách:

Co je zprostředkovatel

Zprostředkovatel autentizace je komponenta, která běží na počítači uživatele a spravuje autentizační procesy a životní cyklus tokenů pro připojené účty. V Windows tuto roli provádí Správce webových účtů (WAM). Mezi klíčové výhody patří:

• Lepší zabezpečení. Vylepšení zabezpečení se doručují prostřednictvím aktualizací operačního systému nebo zprostředkovatele bez nutnosti změn kódu aplikace. Obnovovací tokeny jsou vázané na zařízení a jsou chráněné před exfiltrací.
• Podpora funkcí Přístup k rozsáhlým možnostem operačního systému, jako jsou Windows Hello, zásady podmíněného přístupu Microsoft Entra a bezpečnostní klíče FIDO (Fast Identity Online), bez dalšího podpůrného kódu.
• Integrace systému. Aplikace se připojují k integrovanému výběru účtu a umožňují uživatelům rychle vybrat existující účet místo opětovného zadávání přihlašovacích údajů.
• Ochrana tokenů. Zprostředkovatel zajišťuje, že obnovovací tokeny jsou vázané na zařízení a umožňuje aplikacím získávat přístupové tokeny pro ověření vlastnictví.

Podporované architektury

• Windows: x64, x86, ARM64

Předpoklady

• Node.js 18 nebo novější
• Nainstalujte @azure/msal-node-extensions jako závislost
• Zaregistrujte identifikátor URI přesměrování zprostředkovatele při registraci vaší aplikace. Požadovanou hodnotu najdete v části Identifikátor URI pro přesměrování.

Přesměrování URI

Na portálu Azure zaregistrujte následující identifikátor URI přesměrování na platformě mobilních a desktopových aplikací:

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

Nahraďte <your-client-id> ID klienta vaší aplikace.

Povolení funkce

Povolení zprostředkování tokenů vyžaduje pouze jeden parametr konfigurace. Předejte instanci NativeBrokerPlugin v konfiguraci brokeru:

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

Funkční ukázku najdete v ukázce auth-code-cli-brokered-app.

Nadřazení oken

Pokud chcete, aby se při volání aplikace zobrazovaly výzvy k ověření a blokovaly další interakci, zadejte do acquireTokenInteractive rozhraní API popisovač okna aplikace.

V případě aplikací CLI se na pozadí provede pokus v maximální možné míře o nalezení popisovače okna, ale tento postup není spolehlivý.

Pokud používáte elektron, použijte getNativeWindowHandle rozhraní API a předejte výsledek do acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Doklad o vlastnictví

Ověření vlastnictví přístupového tokenu (PoP) se podporuje při získávání tokenů prostřednictvím nativního zprostředkovatele. Chcete-li požádat o token PoP, přidejte do objektu požadavku předaného do acquireTokenInteractive nebo acquireTokenSilent následující vlastnosti:

Parametry požadavku AT PoP

Příklad použití

Tento příklad požaduje token pro ověření vlastnictví nastavením schématu ověřování a vlastností podepsaného požadavku 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);

Rozdíly při použití zprostředkovatele Windows

Při získávání tokenů prostřednictvím nativního zprostředkovatele může několik věcí fungovat odlišně:

• Parametr forceRefresh pro acquireTokenSilent volání není podporován. Token uložený v mezipaměti můžete obdržet od zprostředkovatele bez ohledu na to, na co je tento příznak nastavený.
• Pokud zprostředkovatel potřebuje vyzvat uživatele k interakci, otevře se výzva systému. Tím se uživatelské prostředí (UX) změní, protože v okně prohlížeče nedojde k ověřování.
• Důkaz o vlastnictví přístupového tokenu je podporován zprostředkovatelem, ale není podporován tokem bez zprostředkovatele.