Libreria client di Identità di Azure per JavaScript - versione 4.4.1
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.
-
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
- Versioni più recenti di Safari, Chrome, Edge e Firefox.
-
Nota: tra le diverse credenziali esportate in questa libreria,
InteractiveBrowserCredential
è l'unico supportato nel browser.
-
Nota: tra le diverse credenziali esportate in questa libreria,
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 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
- 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.
- È disponibile una sezione
Per i flussi di lavoro di autenticazione avanzati nel browser, è disponibile una sezione in cui viene illustrato come usare la libreria
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 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
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:
-
Environment: il
DefaultAzureCredential
leggerà le informazioni sull'account specificate tramite variabili di ambiente e usarle per l'autenticazione. -
'identità del carico di lavoro: se l'applicazione viene distribuita nel servizio Azure Kubernetes con identità gestita abilitata,
DefaultAzureCredential
eseguirà l'autenticazione. -
identità gestita: se l'applicazione viene distribuita in un host di Azure con identità gestita abilitata, il
DefaultAzureCredential
eseguirà l'autenticazione con tale account. -
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, ilDefaultAzureCredential
eseguirà l'autenticazione con tale account. -
di Azure PowerShell: se lo sviluppatore ha eseguito l'autenticazione usando il comando
Connect-AzAccount
del modulo di Azure PowerShell, ilDefaultAzureCredential
eseguirà l'autenticazione con tale account. -
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, ilDefaultAzureCredential
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 diaccess_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
- 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 authorityHost
di 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
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.
Azure SDK for JavaScript