Używanie węzła biblioteki MSAL z natywnym brokerem tokenów (Windows)

węzeł Microsoft Authentication Library (MSAL) obsługuje uzyskiwanie tokenów z natywnego brokera tokenów. W przypadku korzystania z natywnego brokera tokeny odświeżania są powiązane z urządzeniem, na którym zostały pozyskane, i nie są dostępne dla msal-node ani dla aplikacji. Zapewnia to wyższy poziom bezpieczeństwa, którego nie można osiągnąć za pomocą samego msal-node.

W tym artykule wyjaśniono, jak skonfigurować brokera Windows, skonfigurować dowód posiadania i zrozumieć zachowanie specyficzne dla brokera.

Obsługa brokera jest dostępna na następujących platformach:

Platform	Broker	Dokumentacja
Windows	Menedżer kont sieci Web (WAM)	broker systemu Windows (ten artykuł)
macOS	Wtyczka Microsoft Enterprise SSO (Portal firmy)	Broker systemu macOS
Linux	Microsoft — pojedyncze logowanie dla systemu Linux	Broker Linux

Co to jest broker

Broker uwierzytelniania to komponent działający na komputerze użytkownika, który obsługuje proces uzgadniania uwierzytelnienia i zarządza cyklem życia tokenu dla połączonych kont. W Windows ta rola jest wykonywana przez Menedżera kont sieci Web (WAM). Najważniejsze korzyści to:

• Zwiększone zabezpieczenia. Ulepszenia zabezpieczeń są dostarczane za pośrednictwem systemu operacyjnego lub aktualizacji brokera bez konieczności wprowadzania zmian w kodzie aplikacji. Tokeny odświeżania są powiązane z urządzeniem i chronione przed eksfiltracją.
• Obsługiwane funkcje Dostęp do rozbudowanych możliwości systemu operacyjnego, takich jak Windows Hello, zasady dostępu warunkowego Microsoft Entra i klucze zabezpieczeń Fast Identity Online (FIDO), bez dodatkowego kodu pomocniczego.
• Integracja systemu. Aplikacje są podłączane do wbudowanego selektora kont, co umożliwia użytkownikom szybkie wybranie istniejącego konta zamiast ponownego wprowadzania poświadczeń.
• Ochrona tokenów. Broker zapewnia, że tokeny odświeżania są powiązane z urządzeniem i umożliwia aplikacjom uzyskiwanie tokenów dostępu typu proof-of-possession.

Obsługiwane architektury

• Windows: x64, x86, ARM64

Wymagania wstępne

• Node.js 18 lub nowsza wersja
• Zainstaluj @azure/msal-node-extensions jako zależność
• Zarejestruj adres URI przekierowania brokera w rejestracji Twojej aplikacji. Wymaganą wartość znajdziesz w sekcji URI przekierowania.

URI przekierowania

Zarejestruj następujący adres URI przekierowania w ramach platformy Aplikacje mobilne i klasyczne w portalu Azure:

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

Zastąp element <your-client-id> identyfikatorem klienta aplikacji.

Włączanie funkcji

Włączenie brokera tokenów wymaga tylko jednego parametru konfiguracji. Przekaż instancję NativeBrokerPlugin w konfiguracji brokera:

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 nie przejdzie na przepływ bez brokera w razie awarii. Włącz przepływ brokera tylko w środowiskach, które go obsługują, aby uniknąć nieoczekiwanych błędów.

Przykład pracy można znaleźć w przykładzie auth-code-cli-brokered-app.

Rodzicielstwo okien

Aby monity o uwierzytelnienie wyświetlały się za pośrednictwem aplikacji wywołującej i blokowały dalszą interakcję, podaj dojście okna aplikacji do interfejsu acquireTokenInteractive API.

W przypadku aplikacji CLI w tle podejmowana jest próba znalezienia uchwytu okna, ale metoda ta nie jest niezawodna.

Jeśli używasz Electron, użyj interfejsu API getNativeWindowHandle i przekaż wynik do acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Dowód posiadania

Token dostępu z potwierdzeniem posiadania (PoP) jest obsługiwany podczas uzyskiwania tokenów za pośrednictwem brokera natywnego. Aby zażądać tokenu poP, dodaj następujące właściwości do obiektu żądania dostarczonego do acquireTokenInteractive lub acquireTokenSilent:

Parametry żądania AT PoP

Nazwa	Description	Wymagane
authenticationScheme	Wskazuje, czy MSAL powinien pozyskać token Bearer lub PoP. Wartość domyślna to Bearer.	Required
resourceRequestMethod	Nazwa metody HTTP żądania, zapisana wielkimi literami, która będzie używać podpisanego tokenu (GET, POST, PUT itp.)	Required
resourceRequestUri	Adres URL chronionego zasobu, dla którego jest wystawiany token dostępu	Required
shrNonce	Wygenerowany przez serwer podpisany znacznik czasu zakodowany w formacie Base64URL jako ciąg. Ta wartość nonce służy do ograniczania skutków rozbieżności zegara oraz ataków typu time-travel, których celem jest umożliwienie wcześniejszego wygenerowania tokenu PoP.	Fakultatywny

Przykład użycia

W tym przykładzie żąda się tokenu potwierdzenia posiadania przez ustawienie schematu uwierzytelniania i właściwości podpisanego żądania 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);

Note

Potwierdzenie posiadania tokenu dostępu jest obsługiwane tylko w natywnym przepływie z brokerem i nie jest dostępne w przepływie bez użycia brokera.

Różnice w przypadku korzystania z brokera Windows

Istnieje kilka rzeczy, które mogą zachowywać się inaczej podczas uzyskiwania tokenów za pośrednictwem brokera natywnego:

• Parametr forceRefresh wywołań acquireTokenSilent nie jest obsługiwany. Możesz otrzymać token z pamięci podręcznej od brokera niezależnie od ustawienia tej flagi.
• Jeśli broker musi monitować użytkownika o interakcję, zostanie otwarty monit systemowy. Spowoduje to zmianę środowiska użytkownika (UX), ponieważ uwierzytelnianie nie występuje w oknie przeglądarki.
• Potwierdzenie posiadania tokenu dostępu jest obsługiwane przez brokera, ale nie jest obsługiwane przez przepływ niewykorzystujący brokera.