Condividi tramite

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

  • Articolo

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:

Introduttiva

Ambienti attualmente supportati

  • versioni LTS di Node.js
  • Versioni più recenti di Safari, Chrome, Edge e Firefox.
    • Nota: tra le diverse credenziali esportate in questa libreria, InteractiveBrowserCredential è l'unica supportata nel browser.

Per altre informazioni, 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> funziona 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 scenari avanzati, gli sviluppatori potrebbero voler usare Microsoft Authentication Library per JavaScript (MSAL.js) direttamente. Prendere in considerazione l'uso di MSAL.js negli scenari seguenti:

  • Sviluppatori che vogliono il controllo completo del protocollo di autenticazione e della relativa configurazione.
  • I tipi di credenziali sono progettati per essere usati con i client Azure SDK con l'aggiornamento intelligente della cache e del token gestito a livello HTTP principale. Se si riscontra la necessità di usare direttamente getToken, è possibile trarre vantaggio dall'uso di MSAL.js per un maggiore controllo sul flusso di autenticazione e sulla memorizzazione nella cache dei token.

Per altre informazioni, vedere i collegamenti seguenti:

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 avvia il browser per autenticare l'utente.

Per i sistemi senza un Web browser predefinito, il comando azd auth login --use-device-code usa 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 , eseguire il comando az login. Per gli utenti in esecuzione in un sistema con un Web browser predefinito, l'interfaccia della riga di comando di Azure avvia il browser per autenticare l'utente.

account dell'interfaccia della riga di comando di Azure

Per i sistemi senza un Web browser predefinito, il comando az login usa 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.

accesso al codice del dispositivo dell'account dell'interfaccia della riga di comando di Azure

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 Azure PowerShell, eseguire il cmdlet Connect-AzAccount. Per impostazione predefinita, come l'interfaccia della riga di comando di Azure, Connect-AzAccount avvia 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 impone al cmdlet di usare invece 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 l'autenticazione delle richieste da parte di un client del servizio. 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 l'ID Microsoft Entra e offre varie 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 un TokenCredential.

Vedere classi di credenziali.

DefaultAzureCredential

DefaultAzureCredential semplifica l'autenticazione durante lo sviluppo di app distribuite in Azure combinando le credenziali usate negli ambienti di hosting di Azure con le credenziali usate nello sviluppo locale. Per altre informazioni, vedere Panoramica di DefaultAzureCredential.

Criteri di continuazione

A partire dalla versione 3.3.0, DefaultAzureCredential tenta 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 continua con le credenziali successive nel flusso. Le credenziali del servizio distribuite arrestano il flusso con un'eccezione generata se sono in grado di tentare il recupero del token, ma non ne ricevono 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 rendere persistenti tra le sessioni, ovvero che 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 DefaultAzureCredential

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

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// 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 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 ChainedTokenCredential

Anche se 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. In questo esempio viene illustrata la creazione di un ChainedTokenCredential che tenta 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";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// 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
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:

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'enumerazione 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 { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

In alternativa a specificare l'argomento authorityHost, è anche possibile impostare la variabile di ambiente AZURE_AUTHORITY_HOST sull'URL dell'autorità del cloud. Questo approccio è utile quando si configurano più credenziali per l'autenticazione nello stesso cloud o quando l'ambiente distribuito deve definire il cloud di destinazione:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

L'enumerazione AzureAuthorityHosts definisce le autorità per i cloud noti per comodità; Tuttavia, se l'autorità per il cloud non è elencata in AzureAuthorityHosts, è possibile passare qualsiasi URL di autorità valido come argomento stringa. Ad esempio:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

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

Catene di credenziali

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

Autenticare le applicazioni ospitate in Azure

Credenziale Uso 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 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 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 (facoltativo) password del file di certificato, se presente
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN (facoltativo) Inviare la catena di certificati nell'intestazione x5c per supportare l'autenticazione basata su nome soggetto/autorità di certificazione

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, viene 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 altre informazioni, 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.

impressioni