Libreria client di Identità di Azure per JavaScript - versione 4.2.0

La libreria di identità di Azure fornisce Microsoft Entra ID (in precedenza Azure Active Directory) l'autenticazione dei token tramite un set di implementazioni utili di TokenCredential.

Per esempi di varie credenziali, vedere la pagina Esempi di identità di Azure.

Collegamenti principali:

• Codice sorgente
• Pacchetto (npm)
• Documentazione di riferimento sulle API
• Documentazione di Microsoft Entra ID
• Esempi

Guida introduttiva

Eseguire la migrazione da v1 a v2 di @azure/identity

Se si usa v1 di @azure/identity, vedere la guida alla migrazione per l'aggiornamento alla versione 2.

Ambienti attualmente supportati

• Versioni LTS di Node.js
  • Nota: Se l'applicazione viene eseguita in Node.js v8 o versione inferiore e non è possibile aggiornare la versione Node.js alla versione stabile più recente, aggiungere la @azure/identity dipendenza alla versione 1.1.0.
• Ultime versioni di Safari, Chrome, Edge e Firefox.
  • Nota: tra le diverse credenziali esportate in questa libreria, InteractiveBrowserCredential è l'unica che è supportata nel browser.

Per altre informazioni, vedere i criteri di supporto.

Installare il pacchetto

Installare Azure Identity con npm:

npm install --save @azure/identity

Prerequisiti

• Una sottoscrizione di Azure.
• Facoltativo: l'interfaccia della riga di comando di Azure e/o la Azure PowerShell può essere utile anche per l'autenticazione in un ambiente di sviluppo e la gestione dei ruoli dell'account.

Quando usare @azure/identity

Le classi di credenziali esposte da @azure/identity sono incentrate sul modo più semplice per autenticare i client azure SDK in locale, negli ambienti di sviluppo e in produzione. Si mira alla semplicità e al supporto ragionevole dei protocolli di autenticazione per coprire la maggior parte degli scenari di autenticazione possibili in Azure. Stiamo espandendo attivamente per coprire più scenari. Per un elenco completo delle credenziali offerte, vedere la sezione Classi di credenziali .

Tutti i tipi di credenziali forniti da @azure/identity sono supportati in Node.js. Per i browser, InteractiveBrowserCredential è il tipo di credenziale da usare per gli scenari di autenticazione di base.

La maggior parte dei tipi di credenziali offerti tramite @azure/identityMicrosoft Authentication Library for JavaScript (MSAL.js). In particolare, si usano le librerie di MSAL.js v2, che usano il flusso di codice di autorizzazione OAuth 2.0 con PKCE e sono conformi a OpenID. Mentre @azure/identity si concentra sulla semplicità, le librerie MSAL.js, ad esempio @azure/msal-common, @azure/msal-node e @azure/msal-browser, sono progettate per fornire supporto affidabile per i protocolli di autenticazione supportati da Azure.

Quando usare un altro elemento

I @azure/identity tipi di credenziali sono implementazioni della classe @azure/core-authTokenCredential. In principio, qualsiasi oggetto con un getToken metodo che soddisfa getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> funzionerà come TokenCredential. Ciò significa che gli sviluppatori possono scrivere i propri tipi di credenziali per supportare i casi di autenticazione non coperti da @azure/identity. Per altre informazioni, vedere Credenziali personalizzate.

Anche se i tipi di credenziali supportano molti casi avanzati, gli sviluppatori potrebbero voler controllare completamente il protocollo di autenticazione. Per questo caso d'uso, è consigliabile usare direttamente Microsoft Authentication Library per JavaScript (MSAL.js). Per altre informazioni, vedere i collegamenti seguenti:

• Vengono illustrati alcuni casi d'uso avanzati della pagina Esempi di identità di @azure/identityAzure .
  • In questa sezione sono disponibili in particolare esempi avanzati .
  • È disponibile anche una sezione che illustra come eseguire l'autenticazione con MSAL direttamente.

Per i flussi di lavoro di autenticazione avanzati nel browser, è disponibile una sezione in cui viene illustrato come usare la libreria @azure/msal-browser direttamente per autenticare i client azure SDK.

Autenticare il client nell'ambiente di sviluppo

Anche se è consigliabile usare l'autenticazione dell'identità gestita o dell'entità servizio nell'applicazione di produzione, per uno sviluppatore è normale usare il proprio account per autenticare le chiamate ai servizi di Azure durante il debug e l'esecuzione del codice in locale. Esistono diversi strumenti di sviluppo che possono essere usati per eseguire questa autenticazione nell'ambiente di sviluppo.

Eseguire l'autenticazione tramite il Azure Developer CLI

Gli sviluppatori che codificano all'esterno di un IDE possono usare anche [Azure Developer CLI][azure_developer_cli] per l'autenticazione. Le applicazioni che usano DefaultAzureCredential o AzureDeveloperCliCredential possono quindi autenticare le chiamate nell'applicazione con questo account durante l'esecuzione in locale.

Per eseguire l'autenticazione con [Azure Developer CLI][azure_developer_cli], gli utenti possono eseguire il comando azd auth login. Per gli utenti in esecuzione in un sistema con un Web browser predefinito, il Azure Developer CLI avvierà il browser per autenticare l'utente.

Per i sistemi senza un Web browser predefinito, il comando azd auth login --use-device-code userà il flusso di autenticazione del codice del dispositivo.

Eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure

Le applicazioni che usano , AzureCliCredentialsia direttamente che tramite DefaultAzureCredential, possono usare l'account dell'interfaccia della riga di comando di Azure per autenticare le chiamate nell'applicazione durante l'esecuzione in locale.

Per eseguire l'autenticazione con l'interfaccia della riga di comando di Azure, gli utenti possono eseguire il comando az login. Per gli utenti che eseguono un sistema con un Web browser predefinito, l'interfaccia della riga di comando di Azure avvierà il browser per autenticare l'utente.

Per i sistemi senza un Web browser predefinito, il comando az login userà il flusso di autenticazione del codice del dispositivo. L'utente può anche imporre all'interfaccia della riga di comando di Azure l'uso del flusso del codice del dispositivo invece di avviare un browser specificando l'argomento --use-device-code.

Eseguire l'autenticazione tramite Azure PowerShell

Le applicazioni che usano , AzurePowerShellCredentialsia direttamente che tramite DefaultAzureCredential, possono usare l'account connesso a Azure PowerShell per autenticare le chiamate nell'applicazione durante l'esecuzione in locale.

Per eseguire l'autenticazione con Azure PowerShell gli utenti possono eseguire il Connect-AzAccount cmdlet. Per impostazione predefinita, Connect-AzAccount ike l'interfaccia della riga di comando di Azure avvierà il Web browser predefinito per autenticare un account utente.

Se l'autenticazione interattiva non può essere supportata nella sessione, l'argomento -UseDeviceAuthentication forza il cmdlet a usare invece un flusso di autenticazione del codice del dispositivo, simile all'opzione corrispondente nella credenziale dell'interfaccia della riga di comando di Azure.

Eseguire l'autenticazione tramite Visual Studio Code

Gli sviluppatori che usano Visual Studio Code possono usare l'estensione account di Azure per eseguire l'autenticazione tramite l'editor. Le app che usano VisualStudioCodeCredential possono quindi usare questo account per autenticare le chiamate nell'app durante l'esecuzione in locale.

Per eseguire l'autenticazione in Visual Studio Code, verificare che l'estensione dell'account di Azure sia installata. Dopo l'installazione, aprire il riquadro comandi ed eseguire il comando Azure: Accedi .

Usare inoltre il @azure/identity-vscode pacchetto di plug-in. Questo pacchetto fornisce le dipendenze di VisualStudioCodeCredential e lo abilita. Vedere Plug-in.

Si tratta di un problema noto che VisualStudioCodeCredential non funziona con le versioni dell'estensione account di Azure più recenti di 0.9.11. Una correzione a lungo termine a questo problema è in corso. Nel frattempo, prendere in considerazione l'autenticazione tramite l'interfaccia della riga di comando di Azure.

Autenticare il client nei browser

Per autenticare i client azure SDK all'interno dei Web browser, è InteractiveBrowserCredentialpossibile impostare , che può essere impostato per usare reindirizzamento o popup per completare il flusso di autenticazione. È necessario creare prima una registrazione app Azure nell'portale di Azure per l'applicazione Web.

Concetti chiave

Se si tratta della prima volta che si usa @azure/identity o Microsoft Entra ID, leggere Uso @azure/identity con Microsoft Entra ID prima. Questo documento fornisce una conoscenza più approfondita della piattaforma e come configurare correttamente l'account Azure.

Credenziali

Una credenziale è una classe che contiene o può ottenere i dati necessari per consentire a un client del servizio di autenticare le richieste. I client di servizio in Azure SDK accettano le credenziali quando vengono costruiti. I client di servizio usano queste credenziali per autenticare le richieste al servizio.

La libreria di identità di Azure è incentrata sull'autenticazione OAuth con Microsoft Entra ID e offre un'ampia gamma di classi di credenziali in grado di acquisire un token Microsoft Entra per autenticare le richieste di servizio. Tutte le classi di credenziali in questa libreria sono implementazioni della classe astratta TokenCredential e ognuna di esse può essere usata per costruire client del servizio in grado di eseguire l'autenticazione con TokenCredential.

Vedere Classi di credenziali.

DefaultAzureCredential

È DefaultAzureCredential appropriato per la maggior parte degli scenari in cui l'applicazione deve essere eseguita in Azure. Questo perché combina le credenziali comunemente usate per l'autenticazione quando vengono distribuite con le credenziali usate per l'autenticazione DefaultAzureCredential in un ambiente di sviluppo.

Nota: DefaultAzureCredential è destinato a semplificare l'introduzione all'SDK gestendo scenari comuni con comportamenti predefiniti ragionevoli. Gli sviluppatori che vogliono un maggior controllo o i cui requisiti non vengono soddisfatti dalle impostazioni predefinite dovranno usare altri tipi di credenziali.

Se usato da Node.js, l'utente tenterà di eseguire l'autenticazione DefaultAzureCredential tramite i meccanismi seguenti in ordine:

1. Ambiente : DefaultAzureCredential leggerà le informazioni sull'account specificate tramite variabili di ambiente e la userà per l'autenticazione.
2. Identità del carico di lavoro: se l'applicazione viene distribuita in servizio Azure Kubernetes con l'identità gestita abilitata, DefaultAzureCredential eseguirà l'autenticazione con essa.
3. Identità gestita : se l'applicazione viene distribuita in un host di Azure con identità gestita abilitata, l'autenticazione DefaultAzureCredential verrà eseguita con tale account.
4. Interfaccia della riga di comando di Azure: se lo sviluppatore ha autenticato un account tramite il comando dell'interfaccia della riga di comando di Azure az login , l'autenticazione DefaultAzureCredential verrà eseguita con tale account.
5. Azure PowerShell: se lo sviluppatore ha eseguito l'autenticazione usando il comando del modulo Connect-AzAccount Azure PowerShell, l'autenticazione DefaultAzureCredential verrà eseguita con tale account.
6. Azure Developer CLI: se lo sviluppatore ha autenticato un account tramite il comando Azure Developer CLIazd auth login, l'autenticazione DefaultAzureCredential verrà eseguita con tale account.

Criteri di continuazione

A partire dalla versione 3.3.0, DefaultAzureCredential tenterà di eseguire l'autenticazione con tutte le credenziali degli sviluppatori fino a quando una non riesce, indipendentemente da eventuali errori precedenti delle credenziali degli sviluppatori. Ad esempio, una credenziale per sviluppatori può tentare di ottenere un token e non riuscire, quindi DefaultAzureCredential continuerà a continuare con le credenziali successive nel flusso. Le credenziali del servizio distribuite arresteranno il flusso con un'eccezione generata se sono in grado di tentare il recupero dei token, ma non riceverne uno.

Ciò consente di provare tutte le credenziali degli sviluppatori nel computer mentre si ha un comportamento prevedibile distribuito.

Nota su VisualStudioCodeCredential

A causa di un problema noto, VisualStudioCodeCredential è stato rimosso dalla DefaultAzureCredential catena di token. Quando il problema viene risolto in una versione futura, questa modifica verrà ripristinata.

Plug-in

Identità di Azure per JavaScript fornisce un'API plug-in che consente di fornire determinate funzionalità tramite pacchetti di plug-in separati. Il @azure/identity pacchetto esporta una funzione di primo livello (useIdentityPlugin) che può essere usata per abilitare un plug-in. Sono disponibili due pacchetti di plug-in:

• @azure/identity-broker, che fornisce supporto per l'autenticazione broker tramite un broker nativo, ad esempio Gestione account Web.
• @azure/identity-cache-persistence, che fornisce la memorizzazione nella cache dei token persistenti in Node.js usando un sistema di archiviazione sicuro nativo fornito dal sistema operativo. Questo plug-in consente di rendere persistenti i valori memorizzati nella cache access_token tra le sessioni, ovvero che un flusso di accesso interattivo non deve essere ripetuto fino a quando è disponibile un token memorizzato nella cache.

Esempio

Altri esempi dell'uso di diverse credenziali sono disponibili nella pagina degli esempi di Azure Identity

Eseguire l'autenticazione con DefaultAzureCredential

In questo esempio viene illustrata l'autenticazione KeyClient dalla libreria client @azure/keyvault-keys usando .DefaultAzureCredential

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Specificare un'identità gestita assegnata dall'utente con DefaultAzureCredential

Uno scenario relativamente comune prevede l'autenticazione tramite un'identità gestita assegnata dall'utente per una risorsa di Azure. Esplorare l'esempio relativo all'autenticazione di un'identità gestita assegnata dall'utente con DefaultAzureCredential per vedere come viene resa un'attività relativamente semplice che può essere configurata usando variabili di ambiente o nel codice.

Definire un flusso di autenticazione personalizzato con ChainedTokenCredential

Anche se in genere è DefaultAzureCredential il modo più rapido per iniziare a sviluppare applicazioni per Azure, gli utenti più avanzati potrebbero avere la necessità di personalizzare le credenziali considerate durante l'autenticazione. ChainedTokenCredential consente agli utenti di combinare più istanze di credenziali per definire una catena personalizzata di credenziali. In questo esempio viene illustrato come creare un ChainedTokenCredential oggetto che tenterà di eseguire l'autenticazione usando due istanze configurate in modo diverso di ClientSecretCredential, per eseguire quindi l'autenticazione dall'KeyClient@azure/keyvault-keys:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

Supporto delle identità gestite

L'autenticazione dell'identità gestita è supportata tramite le DefaultAzureCredential classi di credenziali o ManagedIdentityCredential direttamente per i servizi di Azure seguenti:

• Servizio app di Azure e Funzioni di Azure
• Azure Arc
• Azure Cloud Shell
• Servizio Azure Kubernetes
• Azure Service Fabric
• Macchine virtuali di Azure
• Set di scalabilità di Azure Macchine virtuali

Per esempi di come usare l'identità gestita per l'autenticazione, vedere gli esempi.

Configurazione del cloud

Credenziali predefinite per l'autenticazione all'endpoint Microsoft Entra per Cloud pubblico di Azure. Per accedere alle risorse in altri cloud, ad esempio Azure per enti pubblici o un cloud privato, configurare le credenziali con l'argomento authorityHost nel costruttore. L'interfaccia AzureAuthorityHosts definisce le autorità per cloud noti. Per il cloud us Government, è possibile creare un'istanza di una credenziale in questo modo:

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

Non tutte le credenziali richiedono questa configurazione. Credenziali che eseguono l'autenticazione tramite uno strumento di sviluppo, ad esempio AzureCliCredential, usano la configurazione di tale strumento. Analogamente, accetta un authorityHost argomento ma VisualStudioCodeCredential viene predefinito l'impostazione authorityHost Azure di Visual Studio Code corrispondente: Cloud.

Classi di credenziali

Autenticare le applicazioni ospitate in Azure

Credenziale	Utilizzo	Esempio
DefaultAzureCredential	Offre un'esperienza di autenticazione semplificata per iniziare rapidamente a sviluppare applicazioni eseguite in Azure.	Esempio
ChainedTokenCredential	Consente agli utenti di definire flussi di autenticazione personalizzati che compongono più credenziali.	Esempio
EnvironmentCredential	Autentica un'entità servizio o un utente tramite le informazioni sulle credenziali specificate nelle variabili di ambiente.	Esempio
ManagedIdentityCredential	Autentica l'identità gestita di una risorsa di Azure.	Esempio
WorkloadIdentityCredential	Supporta ID dei carichi di lavoro di Microsoft Entra in Kubernetes.	Esempio

Autenticare le entità servizio

Credenziale	Utilizzo	Esempio	Riferimento
ClientAssertionCredential	Autentica un'entità servizio usando un'asserzione client firmata.	Esempio	Autenticazione di un'entità servizio
ClientCertificateCredential	Autentica un'entità servizio usando un certificato.	Esempio	Autenticazione di un'entità servizio
ClientSecretCredential	Autentica un'entità servizio usando un segreto.	Esempio	Autenticazione di un'entità servizio

Autenticare gli utenti

Credenziale	Utilizzo	Esempio	Riferimento
AuthorizationCodeCredential	Autentica un utente con un codice di autorizzazione ottenuto in precedenza.	Esempio	Codice di autenticazione OAuth2
DeviceCodeCredential	Autentica un utente in modo interattivo nei dispositivi con interfaccia utente limitata.	Esempio	Autenticazione con codice del dispositivo
InteractiveBrowserCredential	Autentica un utente in modo interattivo con il browser di sistema predefinito. Per altre informazioni, fare clic qui.	Esempio	Codice di autenticazione OAuth2
OnBehalfOfCredential	Propaga l'identità utente e le autorizzazioni delegate tramite la catena di richieste		Autenticazione per conto dell'utente
UsernamePasswordCredential	Autentica un utente con un nome utente e una password.	Esempio	Autenticazione con nome utente e password

Eseguire l'autenticazione tramite strumenti di sviluppo

Credenziale	Utilizzo	Esempio	Riferimento
AzureCliCredential	Esegue l'autenticazione in un ambiente di sviluppo con l'interfaccia della riga di comando di Azure.	Esempio	Autenticazione con interfaccia della riga di comando di Azure
AzureDeveloperCliCredential	Eseguire l'autenticazione in un ambiente di sviluppo con l'utente o l'entità servizio abilitati in Azure Developer CLI.		Informazioni di riferimento Azure Developer CLI
AzurePowerShellCredential	Eseguire l'autenticazione in un ambiente di sviluppo usando Azure PowerShell.	Esempio	Azure PowerShell autenticazione
VisualStudioCodeCredential	Esegue l'autenticazione come utente connesso all'estensione dell'account di Azure di Visual Studio Code.		Estensione Azure Account per Visual Studio Code

Variabili di ambiente

DefaultAzureCredential e EnvironmentCredential possono essere configurati con le variabili di ambiente. Ogni tipo di autenticazione richiede valori per variabili specifiche.

Entità servizio con segreto

Nome variabile	Valore
AZURE_CLIENT_ID	ID di un'applicazione Microsoft Entra
AZURE_TENANT_ID	ID del tenant di Microsoft Entra dell'applicazione
AZURE_CLIENT_SECRET	Uno dei segreti client dell'applicazione

Entità servizio con certificato

Nome variabile	Valore
AZURE_CLIENT_ID	ID di un'applicazione Microsoft Entra
AZURE_TENANT_ID	ID del tenant di Microsoft Entra dell'applicazione
AZURE_CLIENT_CERTIFICATE_PATH	percorso di un file di certificato con codifica PEM, inclusa la chiave privata
AZURE_CLIENT_CERTIFICATE_PASSWORD	password del file di certificato, se presente

Nome utente e password

Nome variabile	Valore
AZURE_CLIENT_ID	ID di un'applicazione Microsoft Entra
AZURE_TENANT_ID	ID del tenant di Microsoft Entra dell'applicazione
AZURE_USERNAME	Nome utente (in genere un indirizzo di posta elettronica)
AZURE_PASSWORD	Password di tale utente

La configurazione viene eseguita nell'ordine precedente. Se ad esempio sono presenti sia i valori di un segreto client che quelli di un certificato, verrà usato il segreto client.

Valutazione dell'accesso continuo

A partire dalla versione 3.3.0, l'accesso alle risorse protette dalla valutazione dell'accesso continuo (CAE) è possibile su base richiesta. Questa opzione può essere abilitata usando l'APIGetTokenOptions.enableCae(boolean). L'autorità di certificazione non è supportata per le credenziali dello sviluppatore.

Memorizzazione nella cache dei token

La memorizzazione nella cache dei token è una funzionalità fornita dalla libreria di identità di Azure che consente alle app di:

• Token di cache in memoria (impostazione predefinita) e su disco (consenso esplicito).
• Migliorare la resilienza e le prestazioni.
• Ridurre il numero di richieste effettuate in Microsoft Entra ID per ottenere i token di accesso.

La libreria di identità di Azure offre la memorizzazione nella cache dei dischi persistenti e in memoria. Per altre informazioni, vedere la documentazione sulla memorizzazione nella cache dei token.

Autenticazione negoziata

Un broker di autenticazione è un'applicazione che viene eseguita nel computer di un utente e gestisce le handshake di autenticazione e la manutenzione dei token per gli account connessi. Attualmente è supportato solo Windows Web Account Manager (WAM). Per abilitare il supporto, usare il @azure/identity-broker pacchetto. Per informazioni dettagliate sull'autenticazione tramite WAM, vedere la documentazione del plug-in broker.

Risoluzione dei problemi

Per assistenza alla risoluzione dei problemi, vedere la guida alla risoluzione dei problemi.

Passaggi successivi

Leggi la documentazione

La documentazione sull'API per questa libreria è disponibile nel sito della documentazione.

Supporto della libreria client

Le librerie client e di gestione elencate nella pagina versioni di Azure SDK che supportano l'autenticazione Microsoft Entra accettano le credenziali da questa libreria. Altre informazioni sull'uso di queste librerie nella relativa documentazione, collegata dalla pagina delle versioni.

Problemi noti

Supporto di Azure AD B2C

Questa libreria non supporta il servizio Azure AD B2C .

Per altri problemi aperti, vedere il repository GitHub della libreria.

Inviare commenti e suggerimenti

Se si riscontrano bug o si hanno suggerimenti, aprire un problema.

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.