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

La libreria di identità di Azure fornisce microsoft Entra ID (in precedenza Azure Active Directory) tramite un set di implementazioni TokenCredential.

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

Collegamenti chiave:

• codice sorgente
• pacchetto (npm)
• documentazione di riferimento dell'API
• documentazione di Microsoft Entra ID
• esempi di

Introduttiva

Ambienti attualmente supportati

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

Per altri dettagli, vedere i criteri di supporto .

Installare il pacchetto

Installare l'identità di Azure con npm:

npm install --save @azure/identity

Prerequisiti

• Una sottoscrizione di Azure .
• Facoltativo: l'interfaccia della riga di comando di Azure e/o 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 nell'ambiente di produzione. L'obiettivo è la semplicità e il supporto ragionevole dei protocolli di autenticazione per coprire la maggior parte degli scenari di autenticazione possibili in Azure. Stiamo espandendo attivamente per coprire altri 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 da @azure/identity usa Microsoft Authentication Library per JavaScript (MSAL.js). In particolare, si usano le librerie di MSAL.js v2, che usano flusso di codice di autorizzazione OAuth 2.0 con pkCE e sono conforme a OpenID. Sebbene @azure/identity si concentri sulla semplicità, le librerie di MSAL.js, ad esempio @azure/msal-common, @azure/msal-nodee @azure/msal-browser, sono progettate per offrire un supporto affidabile per i protocolli di autenticazione supportati da Azure.

Quando usare qualcos'altro

I tipi di credenziali sono implementazioni della classe @azure/core-auth. In linea di principio, qualsiasi oggetto con un metodo di getToken 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 di @azure/identity nella pagina esempi di identità di Azure.
  • È disponibile una sezione esempi avanzati.
  • È disponibile anche una sezione che illustra come Autenticare direttamente con MSAL.

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

Sebbene sia consigliabile usare l'identità gestita nell'applicazione ospitata in Azure, in genere uno sviluppatore usa il proprio account per l'autenticazione delle 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 l'interfaccia della riga di comando per sviluppatori di Azure

Gli sviluppatori che codificano all'esterno di un IDE possono anche usare l'interfaccia della riga di comando per sviluppatori di Azure per l'autenticazione. Le applicazioni che usano il DefaultAzureCredential o il AzureDeveloperCliCredential possono quindi usare questo account per autenticare le chiamate nell'applicazione durante l'esecuzione in locale.

Per eseguire l'autenticazione con l'interfaccia della riga di comando per sviluppatori di Azure , gli utenti possono eseguire il comando azd auth login. Per gli utenti in esecuzione in un sistema con un Web browser predefinito, l'interfaccia della riga di comando per sviluppatori di Azure 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 il AzureCliCredential, direttamente o tramite il 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 . Per gli utenti in esecuzione in 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 forzare l'interfaccia della riga di comando di Azure a usare il flusso del codice del dispositivo anziché avviare un browser specificando l'argomento --use-device-code.

Eseguire l'autenticazione tramite Azure PowerShell

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

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

di accesso dell'account Azure PowerShell

Se non è possibile supportare l'autenticazione interattiva nella sessione, l'argomento -UseDeviceAuthentication forza invece il cmdlet a usare un flusso di autenticazione del codice del dispositivo, simile all'opzione corrispondente nelle credenziali 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 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 account di Azure sia installata. Dopo l'installazione, aprire il riquadro comandi ed eseguire il comando Azure: Accedi.

Inoltre, usare il pacchetto plug-in @azure/identity-vscode. Questo pacchetto fornisce le dipendenze di VisualStudioCodeCredential e la abilita. Vedere Plugins.

Si tratta di un problema noto che VisualStudioCodeCredential non funziona con 'estensione account Azure versioni più recenti di 0.9.11. È in corso una correzione a lungo termine per questo problema. Nel frattempo, prendere in considerazione '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, viene offerto il InteractiveBrowserCredential, che può essere impostato per l'uso del reindirizzamento o dei popup per completare il flusso di autenticazione. È necessario creare prima un registrazione app di Azure nel portale di Azure per l'applicazione Web.

Concetti chiave

Se è la prima volta che si usa @azure/identity o Microsoft Entra ID, leggere Using @azure/identity with Microsoft Entra ID first. Questo documento fornisce una conoscenza più approfondita della piattaforma e di 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 del servizio usano tali 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 TokenCredential classe astratta e qualsiasi classe può essere usata da per costruire client del servizio in grado di eseguire l'autenticazione con tokenCredential.

Vedere classi di credenziali.

DefaultAzureCredential

Il DefaultAzureCredential è appropriato per la maggior parte degli scenari in cui l'applicazione deve essere eseguita in definitiva in Azure. Ciò è dovuto al fatto che il DefaultAzureCredential combina le credenziali comunemente usate per l'autenticazione quando vengono distribuite con le credenziali usate per l'autenticazione in un ambiente di sviluppo.

Nota: DefaultAzureCredential è progettato per semplificare l'introduzione all'SDK gestendo scenari comuni con comportamenti predefiniti ragionevoli. Gli sviluppatori che vogliono un maggior controllo o il cui scenario non viene gestito dalle impostazioni predefinite devono usare altri tipi di credenziali.

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

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

Criteri di continuazione

A partire dalla versione 3.3.0, DefaultAzureCredential tenterà di eseguire l'autenticazione con tutte le credenziali dello sviluppatore fino a quando una non riesce, indipendentemente da eventuali errori riscontrati nelle credenziali dello sviluppatore precedenti. Ad esempio, una credenziale per sviluppatori può tentare di ottenere un token e non riuscire, quindi DefaultAzureCredential continuerà 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 del token, ma non ne riceveranno uno.

Ciò consente di provare tutte le credenziali dello sviluppatore nel computer con un comportamento prevedibile distribuito.

Nota sulla VisualStudioCodeCredential

A causa di un problema noto , VisualStudioCodeCredential è stato rimosso dalla catena di token DefaultAzureCredential. 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 plug-in separati. Il pacchetto @azure/identity 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 negoziata tramite un broker nativo, ad esempio Gestione account Web.
• @azure/identity-cache-persistence, che fornisce la memorizzazione nella cache dei token persistente in Node.js usando un sistema di archiviazione sicuro nativo fornito dal sistema operativo. Questo plug-in consente ai valori di access_token memorizzati nella cache di rimanere persistenti tra le sessioni, ovvero non è necessario ripetere un flusso di accesso interattivo purché sia disponibile un token memorizzato nella cache.

Esempi

Per altri esempi di uso di varie credenziali, vedere pagina esempi di identità di Azure

Eseguire l'autenticazione con il DefaultAzureCredential

In questo esempio viene illustrata l'autenticazione del KeyClient dalla libreria client @azure/keyvault-keys usando il 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 il DefaultAzureCredential

Uno scenario relativamente comune prevede l'autenticazione tramite un'identità gestita assegnata dall'utente per una risorsa di Azure. Esplorare l'esempio di sull'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 il ChainedTokenCredential

Anche se il DefaultAzureCredential è in genere il modo più rapido per iniziare a sviluppare applicazioni per Azure, gli utenti più avanzati possono voler personalizzare le credenziali considerate durante l'autenticazione. Il ChainedTokenCredential consente agli utenti di combinare più istanze di credenziali per definire una catena di credenziali personalizzata. Questo esempio illustra la creazione di un ChainedTokenCredential che tenterà di eseguire l'autenticazione usando due istanze configurate in modo diverso di ClientSecretCredential, per autenticare quindi il KeyClient dalle chiavi @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

Il di autenticazione dell'identità gestita è supportato tramite le classi di credenziali o direttamente per i servizi di Azure seguenti:

• Servizio app di Azure e Funzioni di Azure
• azure Arc
• di Azure Cloud Shell
• del servizio Azure Kubernetes
• di Azure Service Fabric
• macchine virtuali di Azure
• set di scalabilità di macchine virtuali di Azure

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

Configurazione cloud

Per impostazione predefinita, le credenziali devono essere autenticate nell'endpoint Microsoft Entra per il 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 i cloud noti. Per il cloud del governo degli Stati Uniti, è possibile creare un'istanza di credenziali 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. Le credenziali che eseguono l'autenticazione tramite uno strumento di sviluppo, ad esempio AzureCliCredential, usano la configurazione di tale strumento. Analogamente, VisualStudioCodeCredential accetta un argomento authorityHost, ma per impostazione predefinita corrisponde all'impostazione authorityHostdi Visual Studio Code: Cloud corrispondente a Quella di Visual Studio Code.

Classi di credenziali

Autenticare le applicazioni ospitate in Azure

Credenziale	Uso	Esempio
DefaultAzureCredential	Offre un'esperienza di autenticazione semplificata per avviare rapidamente lo sviluppo di 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 carico di lavoro Di Microsoft Entra in Kubernetes.	esempio

Autenticare le entità servizio

Credenziale	Uso	Esempio	Riferimento
AzurePipelinesCredential	Supporta ID carico di lavoro Di Microsoft Entra in Azure Pipelines.	esempio
ClientAssertionCredential	Autentica un'entità servizio usando un'asserzione client firmata.	esempio	'autenticazione dell'entità servizio
ClientCertificateCredential	Autentica un'entità servizio usando un certificato.	esempio	'autenticazione dell'entità servizio
ClientSecretCredential	Autentica un'entità servizio usando un segreto.	esempio	'autenticazione dell'entità servizio

Autenticare gli utenti

Credenziale	Uso	Esempio	Riferimento
AuthorizationCodeCredential	Autentica un utente con un codice di autorizzazione ottenuto in precedenza.	esempio	codice di autenticazione OAuth2
DeviceCodeCredential	Autentica in modo interattivo un utente nei dispositivi con interfaccia utente limitata.	esempio	'autenticazione del codice del dispositivo
InteractiveBrowserCredential	Autentica in modo interattivo un utente con il browser di sistema predefinito. Altre informazioni su come ciò accade qui.	esempio	codice di autenticazione OAuth2
OnBehalfOfCredential	Propaga l'identità e le autorizzazioni dell'utente delegate tramite la catena di richieste		di autenticazione on-behalf-of
UsernamePasswordCredential	Autentica un utente con un nome utente e una password.	esempio	nome utente e autenticazione password

Eseguire l'autenticazione tramite gli strumenti di sviluppo

Credenziale	Uso	Esempio	Riferimento
AzureCliCredential	Eseguire l'autenticazione in un ambiente di sviluppo con l'interfaccia della riga di comando di Azure.	esempio	di autenticazione dell'interfaccia della riga di comando di Azure
AzureDeveloperCliCredential	Eseguire l'autenticazione in un ambiente di sviluppo con l'utente o l'entità servizio abilitata nell'interfaccia della riga di comando per sviluppatori di Azure.		di riferimento dell'interfaccia della riga di comando per sviluppatori di Azure
AzurePowerShellCredential	Eseguire l'autenticazione in un ambiente di sviluppo usando Azure PowerShell.	esempio	di autenticazione di Azure PowerShell
VisualStudioCodeCredential	Esegue l'autenticazione come utente che ha eseguito l'accesso all'estensione dell'account Azure di Visual Studio Code.		dell'estensione dell'account Azure di VS 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 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 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 del 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 Microsoft Entra dell'applicazione
AZURE_USERNAME	un nome utente (in genere un indirizzo di posta elettronica)
AZURE_PASSWORD	password dell'utente

La configurazione viene tentata nell'ordine precedente. Ad esempio, se i valori per un segreto client e un certificato sono entrambi presenti, verrà usato il segreto client.

Valutazione dell'accesso continuo

A partire dalla versione 3.3.0, è possibile accedere alle risorse protette da valutazione dell'accesso continuo (CAE) per ogni richiesta. Questa opzione può essere abilitata usando l'API GetTokenOptions.enableCae(boolean). CaE non è supportato per le credenziali per sviluppatori.

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:

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

La libreria di identità di Azure offre sia la memorizzazione nella cache dei dischi in memoria che quella persistente. Per altri dettagli, vedere la documentazione relativa alla memorizzazione nella cache dei token .

Autenticazione negoziata

Un broker di autenticazione è un'applicazione che viene eseguita nel computer di un utente e gestisce gli 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 pacchetto @azure/identity-broker. Per informazioni dettagliate sull'autenticazione con WAM, vedere la documentazione del plug-in broker.

Risoluzione dei problemi

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

Passaggi successivi

Leggere la documentazione

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

Supporto della libreria client

Le librerie client e di gestione elencate nella pagina delle versioni di Azure SDK che supportano l'autenticazione di 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 verificano bug o si hanno suggerimenti, aprire un problema.

Contribuire

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