Plug-in Identità di Azure per l'autenticazione negoziata
Questo pacchetto fornisce un plug-in alla libreria di identità di Azure per JavaScript (@azure/identity) che consente l'uso di un broker di autenticazione, ad esempio WAM.
Un gestore di autenticazione è un'applicazione eseguita nel computer di un utente che gestisce gli handshake di autenticazione e la manutenzione dei token per gli account connessi. Attualmente è supportato solo il gestore di autenticazione di Windows, Web Account Manager (WAM).
Introduttiva
import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
Prerequisiti
Installare il pacchetto
Questo pacchetto è progettato per essere usato con Azure Identity per JavaScript. Installare sia @azure/identity che questo pacchetto usando npm:
npm install --save @azure/identity
npm install --save @azure/identity-broker
Ambienti supportati
I plug-in di Identità di Azure per JavaScript supportano versioni stabili (anche numerate) di Node.js a partire dalla versione 18. Anche se i plug-in possono essere eseguiti in altre versioni Node.js, non è garantito alcun supporto.
@azure/identity-broker
non supporta ambienti browser.
Concetti chiave
Se è la prima volta che si usa @azure/identity o Microsoft Entra ID, è consigliabile leggere prima Using @azure/identity with Microsoft Entra ID. Questo documento illustra in modo più approfondito la piattaforma e come configurare correttamente l'account Azure.
Handle di finestra padre
Quando si esegue l'autenticazione con il broker tramite InteractiveBrowserCredential, è necessario un handle di finestra padre per assicurarsi che la finestra di dialogo di autenticazione venga visualizzata correttamente nella finestra di richiesta. Nel contesto delle interfacce utente grafiche nei dispositivi, un handle di finestra è un identificatore univoco assegnato dal sistema operativo a ogni finestra. Per il sistema operativo Windows, questo handle è un valore intero che funge da riferimento a una finestra specifica.
Pass-through dell'account Microsoft (MSA)
Gli account Microsoft sono account personali creati dagli utenti per accedere ai servizi Microsoft. Il pass-through msa è una configurazione legacy che consente agli utenti di ottenere token alle risorse che normalmente non accettano account di accesso del servizio gestito. Questa funzionalità è disponibile solo per le applicazioni proprietarie. Gli utenti che eseguono l'autenticazione con un'applicazione configurata per l'uso del pass-through msa possono impostare legacyEnableMsaPassthrough su true all'interno di InteractiveBrowserCredentialNodeOptions.brokerOptions per consentire l'elenco di questi account personali da WAM.
URI di reindirizzamento
Le applicazioni Microsoft Entra si basano sugli URI di reindirizzamento per determinare dove inviare la risposta di autenticazione dopo l'accesso di un utente. Per abilitare l'autenticazione negoziata tramite WAM, è necessario registrare un URI di reindirizzamento corrispondente al modello seguente all'applicazione:
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}
Plug-in di Identità di Azure
A partire da @azure/identity versione 2.0.0, la libreria client identity per JavaScript include un'API plug-in. Questo pacchetto (@azure/identity-broker) esporta un oggetto plug-in che è necessario passare come argomento alla funzione useIdentityPlugin di primo livello dal pacchetto @azure/identity. Abilitare broker nativo nel programma come indicato di seguito:
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
},
});
Dopo aver chiamato useIdentityPlugin, il plug-in broker nativo viene registrato nel pacchetto @azure/identity e sarà disponibile nel InteractiveBrowserCredential che supporta l'autenticazione del broker WAM. Questa credenziale ha brokerOptions nelle opzioni del costruttore.
Esempi
Dopo aver registrato il plug-in, è possibile abilitare l'autenticazione del broker WAM passando brokerOptions con una proprietà enabled impostata su true a un costruttore di credenziali. Nell'esempio seguente viene usato il InteractiveBrowserCredential.
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
},
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");
Per un esempio completo dell'uso di un'app Electron per il recupero di un handle di finestra, vedere questo esempio.
Usare l'account predefinito per l'accesso
Quando l'opzione useDefaultBrokerAccount è impostata su true, le credenziali tenteranno di usare automaticamente l'account broker predefinito. Se l'uso dell'account predefinito ha esito negativo, la credenziale eseguirà il fallback all'autenticazione interattiva.
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
useDefaultBrokerAccount: true,
parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
},
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");
Risoluzione dei problemi
Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere Azure Identity [guida alla risoluzione dei problemi][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] .
Registrazione
L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
Passaggi successivi
Inviare commenti e suggerimenti
Se si verificano bug o si hanno suggerimenti, aprire un problema.
Contribuire
Per contribuire a questa libreria, vedere la guida contribuire per altre informazioni su come compilare e testare il codice.
Azure SDK for JavaScript