Plugin Azure Identity per l'autenticazione mediata

Questo pacchetto fornisce un plugin alla libreria Azure Identity per JavaScript (@azure/identity) che consente l'uso di un broker di autenticazione come 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 broker di autenticazione di Windows, Web Account Manager (WAM).

Codice sorgente | Campioni | API documentazione | Microsoft Entra ID documentazione

Introduttiva

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

Prerequisiti

• Un abbonamento Azure.

Nota: per lo sviluppo locale con @azure/identity-broker, potrebbe essere necessario installare strumenti aggiuntivi. node-gyp viene utilizzato per compilare componenti aggiuntivi per l'accesso alle API di sistema. I requisiti di installazione sono elencati nel file README node-gyp.

Su Linux, la libreria viene utilizzata libsecret , quindi potrebbe essere necessario installarla. A seconda della distribuzione, sarà necessario eseguire il seguente comando:

• Debian/Ubuntu: sudo apt-get install libsecret-1-dev
• Basato su Red Hat: sudo yum install libsecret-devel
• Arch Linux: sudo pacman -S libsecret

Installare il pacchetto

Questo pacchetto è progettato per essere utilizzato 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

Azure plugin Identity per JavaScript supportano versioni stabili (con numero pari) di Node.js a partire dalla v20. 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 usi @azure/identity o Microsoft Entra ID, ti consigliamo di leggere prima Usando @azure/identity con Microsoft Entra ID. Questo documento ti darà una comprensione più approfondita della piattaforma e di come configurare correttamente il tuo 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.

Passthrough dell'account account Microsoft (MSA)

Gli account Microsoft (MSA) 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 su URI di reindirizzamento per determinare dove inviare la risposta di autenticazione dopo che l'utente ha effettuato l'accesso. 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}

Azure Identity plugin

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.

Note: A partire da @azure/identity versione 4.11.0-beta.1, DefaultAzureCredential fornisce supporto per accedere tramite il Windows Web Account Manager. Abilitare broker nativo nel programma come indicato di seguito:

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

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 di utilizzo di un'app Electron per recuperare una maniglia di finestra, vedi 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

Consulta la guida Azure Identity troubleshooting per dettagli su come diagnosticare vari scenari di guasto.

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 incontri bug o hai suggerimenti, ti preghiamo di aprire una questione.

Contribuire

Se vuoi contribuire a questa libreria, consulta la guida contributi per saperne di più su come costruire e testare il codice.