Az MSAL Node használata natív tokenközvetítővel (Windows)

Microsoft Authentication Library (MSAL) csomópont támogatja a jogkivonatok beszerzését a natív jogkivonat-közvetítőtől. A natív közvetítő használatakor a frissítési tokenek ahhoz az eszközhöz vannak kötve, amelyen megszerezték őket, és a msal-node vagy az alkalmazás számára nem érhetők el. Ez magasabb szintű biztonságot biztosít, amely önmagában msal-node nem érhető el.

Ez a cikk bemutatja, hogyan konfigurálhatja a Windows közvetítőt, állíthat be igazolási igazolást, és hogyan ismerheti meg a közvetítőspecifikus viselkedést.

A közvetítői támogatás a következő platformokon érhető el:

Platform	Broker	Dokumentáció
Windows	Webfiók Kezelő (WAM)	Windows-közvetítőprogram (e cikk)
macOS	Microsoft Vállalati egyszeri bejelentkezés beépülő modul (Céges portál)	macOS-közvetítő
Linux	Microsoft egyszeri bejelentkezés Linuxra	Linux-közvetítő

Mi az a közvetítő?

A hitelesítési közvetítő egy olyan összetevő, amely egy felhasználó gépén fut, és kezeli a csatlakoztatott fiókok hitelesítési kézfogásait és jogkivonat-életciklusát. A Windows ezt a szerepkört a Web Account Manager (WAM) látja el. A legfontosabb előnyök a következők:

• Fokozott biztonság. A biztonsági fejlesztések operációs rendszeren vagy közvetítőfrissítésen keresztül érhetők el anélkül, hogy alkalmazáskód-módosításokat kellene végrehajtaniuk. A frissítési jogkivonatok eszközhöz kötöttek és védettek a kiszivárgás ellen.
• Támogatott funkciók Az operációs rendszer széles körű képességeihez – például a Windows Hellohoz, a Microsoft Entra Feltételes hozzáférési szabályzataihoz és a Fast Identity Online (FIDO) biztonsági kulcsokhoz – való hozzáférés külön segédkód nélkül.
• Rendszerintegráció. Az alkalmazások a beépített fiókválasztóhoz csatlakoznak, így a felhasználók a hitelesítő adatok újbóli megadása helyett gyorsan kiválaszthatják a meglévő fiókokat.
• Tokenvédelem. A közvetítő biztosítja, hogy a frissítési jogkivonatok eszközhöz kötöttek legyenek, és lehetővé teszi az alkalmazások számára a tulajdonjog igazolási hozzáférési jogkivonatok beszerzését.

Támogatott architektúrák

• Windows: x64, x86, ARM64

Prerequisites

• Node.js 18 vagy újabb
• Telepítse a(z) @azure/msal-node-extensions elemet függőségként
• Regisztrálja a közvetítő átirányítási URI-ját az alkalmazásregisztrációban. A szükséges értékért tekintse meg az átirányítási URI-t.

Átirányítási URI

Regisztrálja a következő átirányítási URI-t a Mobil és asztali alkalmazások platformon a Azure portálon:

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

Cserélje le a(z) <your-client-id> elemet az alkalmazás ügyfélazonosítójára.

A funkció engedélyezése

A tokenközvetítés engedélyezéséhez csak egy konfigurációs paraméter szükséges. Adjon át egy NativeBrokerPlugin példányt a közvetítő konfigurációjában:

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 hiba esetén nem fog visszaesni a nem közvetített folyamatba. Csak olyan környezetekben engedélyezze a közvetítőfolyamatot, amelyek támogatják a váratlan hibák elkerülését.

Egy működő példa az auth-code-cli-brokered-app sample mintában található.

Ablakszülőség

Annak érdekében, hogy a hitelesítési kérések megjelenjenek a hívó alkalmazáson keresztül, és letilthassák a további interakciókat, adja meg az alkalmazás ablakkezelőjét az acquireTokenInteractive API-nak.

A CLI-alkalmazások esetében az ablakfogópont megkeresésére tett legjobb kísérlet a motorháztető alatt történik, de megbízhatatlan.

Ha Electront használ, használja az getNativeWindowHandle API-t, és adja át az eredményt a következőnek acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Birtoklási igazolás

A hozzáférési token birtoklásának igazolása (PoP) támogatott a tokenek natív közvetítőalkalmazáson keresztüli beszerzésekor. PoP-token igényléséhez adja hozzá a következő tulajdonságokat a(z) acquireTokenInteractive vagy acquireTokenSilent számára átadott kérési objektumhoz:

AT PoP-kérelem paraméterei

Name	Description	Kötelező
authenticationScheme	Azt jelzi, hogy az MSAL-nak Bearer vagy PoP tokent kell-e lekérnie. Az alapértelmezett érték Bearer.	Required
resourceRequestMethod	Az aláírt tokent használó kérés HTTP-metódusának csupa nagybetűs neve (GET, POST, PUT, stb.)	Required
resourceRequestUri	Annak a védett erőforrásnak az URL-címe, amelyhez a hozzáférési jogkivonatot kibocsátják	Required
shrNonce	Egy szerver által létrehozott, aláírt időbélyeg, amely Base64URL-kódolású karakterlánc. Ez a nonce a PoP-tokenek előzetes generálását lehetővé tevő óraeltolódási és időutazásos támadások kivédésére szolgál.	Választható

Használati példa

Ez a példa a hitelesítési séma és az aláírt HTTP-kérés tulajdonságainak beállításával kér egy tulajdonjog-igazolási jogkivonatot:

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

A hozzáférési jogkivonat tulajdonjogának igazolása csak a natív közvetítőfolyamaton keresztül támogatott, és nem érhető el a nem közvetített folyamatban.

Különbségek a Windows-közvetítő használatakor

Van néhány dolog, amely eltérően működhet a tokenek natív brokeren keresztüli beszerzése során:

• A(z) acquireTokenSilent hívások forceRefresh paramétere nem támogatott. A közvetítőalkalmazástól kaphat gyorsítótárazott tokent, függetlenül attól, hogyan van beállítva ez a jelző.
• Ha a közvetítőprogramnak felhasználói beavatkozást kell kérnie, megnyílik egy rendszerablak. Ez megváltoztatja a felhasználói élményt (UX), mert a hitelesítés nem történik meg a böngészőablakban.
• A hozzáférési jogkivonat birtoklásának igazolását a közvetítő támogatja, a nem közvetített folyamat azonban nem támogatja.