Chaînes d’informations d’identification dans la bibliothèque Azure Identity pour JavaScript

La bibliothèque d’identités Azure fournit des identifiants — des classes publiques qui implémentent l'interface TokenCredential de la bibliothèque Azure Core. Un justificatif d'identité représente un processus d'authentification distinct pour acquérir un jeton d'accès depuis Microsoft Entra ID. Ces informations d’identification peuvent être chaînées pour former une séquence ordonnée de mécanismes d’authentification à essayer.

Fonctionnement des informations d’identification chaînées

Au moment de l’exécution, une chaîne d’informations d’identification tente de s’authentifier à l’aide des premières informations d’identification de la séquence. Si ces informations d’identification ne parviennent pas à acquérir un jeton d’accès, les informations d’identification suivantes de la séquence sont utilisées, et ainsi de suite jusqu’à l’obtention d’un jeton d’accès. Le diagramme de séquence suivant illustre ce comportement.

Pourquoi utiliser des chaînes d'identifiants

Les certificats d'authentification chaînés peuvent offrir les avantages suivants :

• Prise en compte de l’environnement : sélectionne automatiquement les informations d’identification les plus appropriées en fonction de l’environnement dans lequel l’application s’exécute. Sans cela, vous devrez écrire du code comme suit :

  import { 
      ManagedIdentityCredential, 
      AzureCliCredential 
  } from "@azure/identity";
  
  let credential;
  if (process.env.NODE_ENV === "production") {
      credential = new ManagedIdentityCredential();
  } else {
      credential = new AzureCliCredential();
  }
  

• Fluidité des transitions : votre application peut passer du développement local à votre environnement de préproduction ou de production sans modifier le code d’authentification.

• Amélioration de la résilience: inclut un mécanisme de secours qui passe aux informations d’identification suivantes lorsque le précédent ne parvient pas à acquérir un jeton d’accès.

Comment choisir un identifiant chaîné

Il existe deux approches différentes pour le chaînage des informations d'identification :

• « Démonter » une chaîne : commencez par une chaîne préconfigurée et excluez ce dont vous n’avez pas besoin. Pour cette approche, consultez la section Présentation de DefaultAzureCredential.
• « Créer » une chaîne : commencez par une chaîne vide et incluez uniquement ce dont vous avez besoin. Pour cette approche, consultez la section Présentation de ChainedTokenCredential.

Vue d’ensemble de DefaultAzureCredential

DefaultAzureCredential est une chaîne d’informations d’identification préconfigurée et stricte. Elle est conçue pour prendre en charge de nombreux environnements, ainsi que les flux d’authentification et les outils de développement les plus courants. Sous forme graphique, la chaîne sous-jacente ressemble à ceci :

L'ordre dans lequel DefaultAzureCredential tente les informations d’identification est le suivant.

JSON	Informations d'identification	Descriptif	Activée par défaut ?
1	Environnement	Lit une collection de variables d’environnement pour déterminer si un principal de service d’application (utilisateur d’application) est configuré pour l’application. Si c’est le cas, DefaultAzureCredential utilise ces valeurs pour authentifier l’application auprès d’Azure. Cette méthode est le plus souvent utilisée dans les environnements serveur, mais peut également être utilisée lors du développement local.	Oui
2	Identité de charge de travail	Si l’application est déployée sur un hôte Azure avec Workload Identity activé, authentifiez ce compte.	Oui
3	Identité gérée	Si l’application est déployée sur un hôte Azure avec l’identité managée activée, authentifiez l'application auprès d'Azure en utilisant cette identité managée.	Oui
4	Visual Studio Code	Si le développeur s’est authentifié via l’extension Ressources Azure de Visual Studio Code et que le package @azure/identity-vscode est installé, authentifiez ce compte.	Oui
5	Azure CLI	Si le développeur s’est authentifié auprès d’Azure à l’aide de la commande az login d'Azure CLI, authentifiez l’application auprès d’Azure en utilisant ce même compte.	Oui
6	Azure PowerShell	Si le développeur s’est authentifié auprès d’Azure à l’aide de l’applet de commande Connect-AzAccount d'Azure PowerShell, authentifiez l’application auprès d’Azure en utilisant ce même compte.	Oui
7	Azure Developer CLI	Si le développeur s’est authentifié auprès d’Azure à l’aide de la commande azd auth login d'Azure Developer CLI, authentifiez-vous avec ce compte.	Oui
8	Broker	Authentifie en utilisant le compte par défaut connecté au système d'exploitation via un intermédiaire. Nécessite que le package @azure/identity-broker soit installé.	Oui

Dans sa forme la plus simple, vous pouvez utiliser la version sans paramètre de DefaultAzureCredential comme suit :

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
);

Comment personnaliser DefaultAzureCredential

Les sections suivantes décrivent les stratégies de contrôle des informations d’identification incluses dans la chaîne.

Exclure une catégorie de type d’informations d’identification

Pour exclure toutes les informations d'identification de type Developer tool ou Deployed service, définissez la variable d'environnement AZURE_TOKEN_CREDENTIALS sur prod ou dev, respectivement. Lorsqu’une valeur est prod utilisée, la chaîne d’informations d’identification sous-jacente se présente comme suit :

Lorsqu’une valeur est dev utilisée, la chaîne se présente comme suit :

Pour vous assurer que la variable d’environnement est définie et possède une valeur texte prise en charge, définissez la propriété requiredEnvVars sur AZURE_TOKEN_CREDENTIALS:

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

Utiliser des informations d’identification spécifiques

Pour exclure toutes les informations d’identification à l’exception d’une, définissez la variable AZURE_TOKEN_CREDENTIALS d’environnement sur le nom des informations d’identification. Par exemple, vous pouvez réduire la DefaultAzureCredential chaîne en AzureCliCredential définissant AZURE_TOKEN_CREDENTIALS sur AzureCliCredential. La comparaison de chaînes est effectuée de manière non sensible à la casse. Les valeurs de chaîne valides pour la variable d’environnement sont les suivantes :

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Importante

La AZURE_TOKEN_CREDENTIALS variable d’environnement prend en charge les noms d’informations d’identification individuels dans les @azure/identity versions 4.11.0 et ultérieures du package.

Pour vous assurer que la variable d’environnement est définie et réglée sur une chaîne supportée, définissez la propriété requiredEnvVars sur AZURE_TOKEN_CREDENTIALS:

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

Vue d’ensemble de ChainedTokenCredential

ChainedTokenCredential est une chaîne vide à laquelle vous ajoutez des informations d’identification pour répondre aux besoins de votre application. Par exemple:

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’exemple de code précédent crée une chaîne d’informations d’identification personnalisée composée de deux informations d’identification au moment du développement. AzureCliCredential est tentée en premier, suivie de VisualStudioCodeCredential, si nécessaire. Sous forme graphique, la chaîne ressemble à ceci :

Conseil / Astuce

Pour améliorer les performances, optimisez l’ordre des informations d’identification dans ChainedTokenCredential de la plupart aux informations d’identification les moins utilisées.

Conseils d’utilisation pour DefaultAzureCredential

DefaultAzureCredential est sans aucun doute le moyen le plus simple de bien démarrer avec la bibliothèque d’identités Azure, mais avec cette commodité vient des compromis. Une fois que vous avez déployé votre application sur Azure, vous devez comprendre les exigences d’authentification de l’application. Pour cette raison, remplacez DefaultAzureCredential par une implémentation de TokenCredential spécifique, telle que ManagedIdentityCredential.

Voici pourquoi :

• Problèmes de débogage : en cas d’échec de l’authentification, il peut être difficile de déboguer et d’identifier les informations d’identification incriminées. Vous devez activer l'enregistrement pour voir la progression d'un justificatif d'identité à l'autre et l'état de réussite/échec de chacun. Pour plus d’informations, consultez Déboguer des informations d’identification.
• Surcharge des performances : le processus de tentative séquentielle de plusieurs informations d’identification peut introduire une surcharge de performances. Par exemple, lors de l’exécution sur un ordinateur de développement local, l’identité managée n’est pas disponible. En conséquence, ManagedIdentityCredential échoue toujours dans l’environnement de développement local.
• Comportement imprévisible : DefaultAzureCredential vérifie la présence de certaines variables d’environnement. Il est possible que quelqu’un puisse ajouter ou modifier ces variables d’environnement au niveau du système sur l’ordinateur hôte. Ces modifications s’appliquent globalement et modifient donc le comportement de DefaultAzureCredential au moment de l’exécution dans n’importe quelle application s’exécutant sur cet ordinateur.

Déboguer un identifiant

Pour diagnostiquer un problème inattendu ou comprendre ce que les informations d'identification font, activez la journalisation dans votre application. Par exemple:

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.

Dans la sortie précédente, notez que DefaultAzureCredential a acquis un jeton avec succès à l’aide de AzureCliCredential.