Catene di credenziali nella libreria di identità di Azure per JavaScript

La libreria di identità di Azure fornisce le credenziali, ovvero classi pubbliche che implementano l'interfaccia TokenCredential della libreria Core di Azure. Una credenziale rappresenta un flusso di autenticazione distinto per l'acquisizione di un token di accesso da Microsoft Entra ID. Queste credenziali si possono concatenare per formare una sequenza ordinata di meccanismi di autenticazione da tentare.

Funzionamento di una credenziale concatenata

In fase di esecuzione, una catena di credenziali tenta di eseguire l'autenticazione usando la prima credenziale della sequenza. Se tale credenziale non riesce ad acquisire un token di accesso, viene tentata la credenziale successiva nella sequenza e così via finché non viene ottenuto correttamente un token di accesso. Il diagramma di sequenza seguente illustra questo comportamento:

Diagramma di una sequenza di catena di credenziali che mostra i tentativi di autenticazione che passano attraverso più credenziali fino a quando non viene ottenuto un token di accesso.

Perché usare catene di credenziali

Una credenziale concatenata può offrire i vantaggi seguenti:

Riconoscimento dell'ambiente: seleziona automaticamente la credenziale più adeguata in base all'ambiente di esecuzione dell'app. Senza di essa, si dovrebbe scrivere un codice simile al seguente:

import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new AzureCliCredential();
}

transizioni semplici: l'app può passare dallo sviluppo locale all'ambiente di staging o di produzione senza modificare il codice di autenticazione.
Resilienza migliorata: include un meccanismo di fallback che passa alla credenziale successiva se quella precedente non riesce ad acquisire un token di accesso.

Come scegliere una credenziale concatenata

Esistono due approcci diversi per il concatenamento delle credenziali:

"Disinstallare" una catena: iniziare da una catena preconfigurata ed escludere ciò che non serve. Per questo approccio, consultare la sezione panoramica di DefaultAzureCredential.
"Creare" una catena: iniziare da una catena vuota e includere solo ciò che serve. Per questo approccio, vedere la sezione panoramica di ChainedTokenCredential.

Panoramica di DefaultAzureCredential

DefaultAzureCredential è una catena di credenziali preconfigurata e con opinioni definite. È progettato per supportare molti ambienti, insieme ai flussi di autenticazione e agli strumenti di sviluppo più comuni. In forma grafica, la catena sottostante è simile alla seguente:

L'ordine in cui DefaultAzureCredential tenta le credenziali è il seguente.

Ordinamento	Credenziali di accesso	Descrizione	Abilitata per impostazione predefinita?
1	Ambiente	Legge una raccolta di variabili di ambiente per determinare se un'entità servizio dell'applicazione (utente dell'applicazione) sia configurata per l'applicazione. In tal caso, `DefaultAzureCredential` usa questi valori per autenticare l'app in Azure. Questo metodo viene usato più spesso negli ambienti server, ma può essere usato anche durante lo sviluppo in locale.	Yes
2	Identità del carico di lavoro	Se l'app è distribuita in un host di Azure con Identità di Workload abilitata, autentica l'account.	Yes
3	Identità gestita	Se l'app viene distribuita in un host di Azure con identità gestita abilitata, autentica l'app in Azure usando l'identità gestita.	Yes
4	Visual Studio Code	Se lo sviluppatore è stato autenticato tramite l'estensione Risorse di Azure di Visual Studio Code e il pacchetto @azure/identity-vscode viene installato, autenticare tale account.	Yes
5	Interfaccia della riga di comando di Azure	Se lo sviluppatore si è autenticato su Azure utilizzando il comando `az login` dell'Azure CLI, autentica l'app in Azure usando lo stesso account.	Yes
6	Azure PowerShell	Se lo sviluppatore ha eseguito l'autenticazione in Azure usando il cmdlet `Connect-AzAccount` di PowerShell, autenticare l'app in Azure usando lo stesso account.	Yes
7	CLI per sviluppatori di Azure	Se lo sviluppatore ha eseguito l'autenticazione in Azure usando il comando `azd auth login` dell'interfaccia della riga di comando per sviluppatori di Azure, eseguire l'autenticazione con tale account.	Yes
8	Broker	Esegue l'autenticazione usando l'account predefinito connesso al sistema operativo tramite un broker. Richiede l'installazione del pacchetto @azure/identity-broker .	Yes

Nella sua forma più semplice, è possibile usare la versione senza parametri di DefaultAzureCredential, come indicato di seguito:

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

Come personalizzare DefaultAzureCredential

Le sezioni seguenti descrivono le strategie per controllare quali credenziali sono incluse nella catena.

Escludere una categoria del tipo di credenziale

Per escludere tutte le credenziali Developer tool o Deployed service , impostare la variabile di ambiente AZURE_TOKEN_CREDENTIALS rispettivamente su prod o dev. Quando viene usato un valore di prod , la catena di credenziali sottostante è simile alla seguente:

Diagramma di una sequenza di catena di credenziali che mostra i tentativi di autenticazione che passano attraverso più credenziali fino a quando non viene ottenuto un token di accesso.

Quando viene usato un valore di dev , la catena ha l'aspetto seguente:

Diagramma della catena DefaultAzureCredential con AZURE_TOKEN_CREDENTIALS impostato su

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, impostare la proprietà requiredEnvVars su AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Usare credenziali specifiche

Per escludere tutte le credenziali ad eccezione di una, impostare la variabile AZURE_TOKEN_CREDENTIALS di ambiente sul nome delle credenziali. Ad esempio, è possibile ridurre la catena DefaultAzureCredential a AzureCliCredential impostando AZURE_TOKEN_CREDENTIALS su AzureCliCredential. Il confronto tra stringhe viene eseguito senza distinzione tra maiuscole e minuscole. I valori stringa validi per la variabile di ambiente includono:

AzureCliCredential
AzureDeveloperCliCredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Importante

La AZURE_TOKEN_CREDENTIALS variabile di ambiente supporta singoli nomi di credenziali nelle @azure/identity versioni del pacchetto 4.11.0 e successive.

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, impostare la proprietà requiredEnvVars su AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Panoramica di ChainedTokenCredential

ChainedTokenCredential è una catena vuota a cui aggiungere le credenziali in base alle esigenze dell'app. Per esempio:

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

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

L'esempio di codice precedente crea una catena di credenziali personalizzata costituita da due credenziali in fase di sviluppo. Si tenta AzureCliCredential per primo, seguito da VisualStudioCodeCredential, se necessario. In forma grafica, la catena è simile alla seguente:

Diagramma di una catena di credenziali che mostra AzureCliCredential come primo tentativo e VisualStudioCodeCredential come fallback.

Suggerimento

Per migliorare le prestazioni, ottimizzare l'ordinamento delle credenziali in ChainedTokenCredential dalla credenziale più a quella meno usata.

Linee guida sull'utilizzo di DefaultAzureCredential

DefaultAzureCredential è senza dubbio il modo più semplice per iniziare a usare la libreria di identità di Azure, ma con tale praticità si verifica un compromesso. Dopo aver distribuito l'app in Azure, è necessario comprendere i requisiti di autenticazione dell'app. Per questo motivo, sostituire DefaultAzureCredential con un'implementazione di TokenCredential specifica, ad esempio ManagedIdentityCredential.

Ecco perché:

Problematiche di debug: quando l'autenticazione non va a buon fine, può essere difficile eseguire il debug e l'identificazione della credenziale all'origine dell'errore. È necessario abilitare la registrazione per visualizzare il passaggio da una credenziale alla successiva e lo stato di esito positivo/negativo di ognuna di esse. Per altre informazioni, vedere Eseguire il debug di credenziali.
sovraccarico delle prestazioni: il processo di tentativo sequenziale di più credenziali può comportare un sovraccarico delle prestazioni. Ad esempio, quando viene eseguito su una macchina di sviluppo locale, l'identità gestita non è disponibile. Di conseguenza, ManagedIdentityCredential ha sempre esito negativo nell'ambiente di sviluppo locale.
Comportamento imprevedibile: DefaultAzureCredential verifica la presenza di alcune variabili di ambiente. È possibile che un utente possa aggiungere o modificare queste variabili di ambiente a livello di sistema nel computer host. Tali modifiche si applicano a livello globale e quindi modificano il comportamento di DefaultAzureCredential in fase di runtime in qualsiasi app in esecuzione in tale computer.

Eseguire il debug di credenziali

Per diagnosticare un problema imprevisto o per capire cosa sta facendo una credenziale, abilitare la registrazione nell'app. Per esempio:

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

Nell'output precedente, si noti che un token è stato acquisito correttamente usando DefaultAzureCredential con AzureCliCredential.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-10