Uso di MSAL Node con il broker di token nativo (Windows)

Libreria di Autenticazione Microsoft nodo (MSAL) supporta l'acquisizione di token dal broker di token nativo. Quando si usa il broker nativo, i token di aggiornamento vengono associati al dispositivo in cui vengono acquisiti e non sono accessibili da msal-node o dall'applicazione. Ciò garantisce un livello di sicurezza superiore che non può essere raggiunto con il solo msal-node.

Questo articolo illustra come configurare il broker Windows, configurare la verifica del possesso e comprendere il comportamento specifico del broker.

Il supporto broker è disponibile nelle piattaforme seguenti:

Che cos'è un broker

Un broker di autenticazione è un componente eseguito nel computer di un utente e gestisce gli handshake di autenticazione e il ciclo di vita dei token per gli account connessi. In Windows questo ruolo viene eseguito da Web Account Manager (WAM). I vantaggi principali includono:

• Sicurezza avanzata. I miglioramenti della sicurezza vengono distribuiti tramite aggiornamenti del sistema operativo o broker senza richiedere modifiche al codice dell'app. I token di aggiornamento sono associati al dispositivo e protetti dall'esfiltrazione.
• Supporto delle funzionalità. Accesso alle funzionalità avanzate del sistema operativo, come Windows Hello, i criteri di accesso condizionale di Microsoft Entra e le chiavi di sicurezza FIDO (Fast Identity Online), senza codice di supporto aggiuntivo.
• Integrazione del sistema. Le applicazioni si collegano alla selezione account predefinita, consentendo agli utenti di selezionare rapidamente un account esistente invece di immettere nuovamente le credenziali.
• Protezione dei token. Il broker garantisce che i token di aggiornamento siano associati al dispositivo e consentano alle app di acquisire token di accesso di verifica del possesso.

Architetture supportate

• Windows: x64, x86, ARM64

Prerequisiti

• Node.js versione 18 o successive
• Installare @azure/msal-node-extensions come dipendenza
• Registrare l'URI di reindirizzamento del broker nella registrazione dell'app. Per il valore richiesto, vedere URI di reindirizzamento.

URI di reindirizzamento

Registrare l'URI di reindirizzamento seguente nella piattaforma applicazioni per dispositivi mobili e desktop nel portale di Azure:

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

Sostituire <your-client-id> con l'ID client dell'applicazione.

Abilitare la funzionalità

L'abilitazione del brokering di token richiede un solo parametro di configurazione. Passare un'istanza NativeBrokerPlugin nella configurazione del broker:

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

Un esempio funzionante è disponibile nell'esempio auth-code-cli-brokered-app.

Relazione padre-figlio della finestra

Affinché i prompt di autenticazione vengano visualizzati sopra l'applicazione chiamante e impediscano ulteriori interazioni, fornire l'handle della finestra dell'applicazione all'API acquireTokenInteractive.

Per le app CLI, viene effettuato internamente un tentativo, per quanto possibile, di individuare l'handle della finestra, ma il risultato non è affidabile.

Se si usa Electron, usare l'API getNativeWindowHandle e passare il risultato in acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Dimostrazione del possesso

La prova di possesso del token di accesso (PoP) è supportata durante l'acquisizione di token tramite il broker nativo. Per richiedere un token PoP, aggiungere le proprietà seguenti all'oggetto richiesta fornito a acquireTokenInteractive o acquireTokenSilent:

Parametri della richiesta AT PoP

Esempio di utilizzo

In questo esempio viene richiesto un token di verifica del possesso impostando lo schema di autenticazione e le proprietà delle richieste HTTP firmate:

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

Differenze quando si usa il broker Windows

Esistono alcuni aspetti che possono comportarsi in modo diverso durante l'acquisizione di token tramite il broker nativo:

• Il forceRefresh parametro per acquireTokenSilent le chiamate non è supportato. È possibile ricevere un token memorizzato nella cache dal broker indipendentemente da ciò che questo flag è impostato su.
• Se il broker deve richiedere l'interazione all'utente, viene visualizzata una richiesta di sistema. In questo modo l'esperienza utente viene modificata perché l'autenticazione non si verifica in una finestra del browser.
• La prova di possesso del token di accesso è supportata dal broker, ma non è supportata dal flusso non negoziato.