Bibliothèque cliente Azure Identity pour JavaScript - version 4.1.0

La bibliothèque Azure Identity fournit une authentification par jeton Microsoft Entra ID (anciennement Azure Active Directory) par le biais d’un ensemble d’implémentations TokenCredential pratiques.

Pour obtenir des exemples de différentes informations d’identification, consultez la page Exemples d’identité Azure.

Liens clés :

• Code source
• Package (npm)
• Documentation de référence de l’API
• Documentation Microsoft Entra ID
• Exemples

Prise en main

Migrer de v1 vers v2 de @azure/identity

Si vous utilisez v1 de , consultez le guide de @azure/identitymigration pour la mise à jour vers la version 2.

Environnements actuellement pris en charge

• Versions LTS de Node.js
  • Note: Si votre application s’exécute sur Node.js v8 ou une version antérieure et que vous ne pouvez pas mettre à niveau votre version Node.js vers la dernière version stable, épinglez votre @azure/identity dépendance à la version 1.1.0.
• Dernières versions de Safari, Chrome, Edge et Firefox.
  • Remarque : Parmi les différentes informations d’identification exportées dans cette bibliothèque, InteractiveBrowserCredential est la seule qui est prise en charge dans le navigateur.

Pour plus d’informations, consultez notre politique de support .

Installer le package

Installez Azure Identity avec npm :

npm install --save @azure/identity

Prérequis

• Un abonnement Azure.
• Facultatif : Azure CLI et/ou Azure PowerShell peuvent également être utiles pour l’authentification dans un environnement de développement et la gestion des rôles de compte.

Quand utiliser @azure/identity

Les classes d’informations d’identification exposées par @azure/identity sont axées sur la fourniture du moyen le plus simple d’authentifier les clients du KIT de développement logiciel (SDK) Azure localement, dans vos environnements de développement et en production. Nous visons la simplicité et la prise en charge raisonnable des protocoles d’authentification pour couvrir la plupart des scénarios d’authentification possibles sur Azure. Nous développons activement pour couvrir d’autres scénarios. Pour obtenir la liste complète des informations d’identification proposées, consultez la section Classes d’informations d’identification .

Tous les types d’informations d’identification fournis par @azure/identity sont pris en charge dans Node.js. Pour les navigateurs, InteractiveBrowserCredential est le type d’informations d’identification à utiliser pour les scénarios d’authentification de base.

La plupart des types d’informations d’identification proposés par @azure/identity utilisent la bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js). Plus précisément, nous utilisons les bibliothèques MSAL.js v2, qui utilisent le flux de code d’autorisation OAuth 2.0 avec PKCE et sont conformes à OpenID. Bien que @azure/identity se concentre sur la simplicité, les bibliothèques MSAL.js, telles que @azure/msal-common, @azure/msal-node et @azure/msal-browser, sont conçues pour fournir une prise en charge robuste des protocoles d’authentification pris en charge par Azure.

Quand utiliser autre chose

Les @azure/identity types d’informations d’identification TokenCredential sont des implémentations de la classe de @azure/core-auth. En principe, tout objet avec une getToken méthode qui satisfait getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> fonctionne comme un TokenCredential. Cela signifie que les développeurs peuvent écrire leurs propres types d’informations d’identification pour prendre en charge les cas d’authentification non couverts par @azure/identity. Pour plus d’informations, consultez Informations d’identification personnalisées.

Bien que nos types d’informations d’identification prennent en charge de nombreux cas avancés, les développeurs peuvent souhaiter un contrôle total du protocole d’authentification. Pour ce cas d’usage, nous vous recommandons d’utiliser la bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) directement. Pour en savoir plus, consultez les liens suivants :

• Nous dépeinons certains cas d’usage avancés de @azure/identity dans la page Exemples d’identité Azure .
  • Ici, nous avons spécifiquement une section Exemples avancés .
  • Nous avons également une section qui montre comment s’authentifier directement auprès de MSAL.

Pour les workflows d’authentification avancée dans le navigateur, nous avons une section dans laquelle nous présentons comment utiliser la bibliothèque @azure/msal-browser directement pour authentifier les clients du KIT de développement logiciel (SDK) Azure.

Authentifier le client dans l’environnement de développement

Nous vous recommandons d’utiliser l’authentification par identité managée ou par principal de service dans votre application de production. Il est toutefois courant qu’un développeur utilise son propre compte pour authentifier les appels aux services Azure pendant les phases de débogage et d’exécution du code en local. Il existe plusieurs outils de développement qui peuvent servir à cette authentification dans votre environnement de développement.

S’authentifier via le Azure Developer CLI

Les développeurs qui codent en dehors d’un IDE peuvent également utiliser [Azure Developer CLI][azure_developer_cli] pour s’authentifier. Les applications utilisant les DefaultAzureCredential ou AzureDeveloperCliCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.

Pour s’authentifier auprès de [Azure Developer CLI][azure_developer_cli], les utilisateurs peuvent exécuter la commande azd auth login. Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut, le Azure Developer CLI lance le navigateur pour authentifier l’utilisateur.

Sur les systèmes sans navigateur web par défaut, la commande azd auth login --use-device-code utilise le flux d’authentification de code d’appareil.

S’authentifier via Azure CLI

Les applications qui utilisent , AzureCliCredentialque ce soit directement ou via , DefaultAzureCredentialpeuvent utiliser le compte Azure CLI pour authentifier les appels dans l’application lors de l’exécution locale.

Pour une authentification avec Azure CLI, les utilisateurs peuvent exécuter la commande az login. Sur les systèmes avec un navigateur web par défaut, Azure CLI lance le navigateur pour authentifier les utilisateurs.

Sur les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification de code d’appareil. L’utilisateur peut également spécifier l’argument --use-device-code pour forcer Azure CLI à utiliser le flux de code d’appareil au lieu de lancer un navigateur.

S’authentifier via Azure PowerShell

Les applications utilisant , AzurePowerShellCredentialque ce soit directement ou via , DefaultAzureCredentialpeuvent utiliser le compte connecté à Azure PowerShell pour authentifier les appels dans l’application lors de l’exécution locale.

Pour s’authentifier auprès de Azure PowerShell utilisateurs peuvent exécuter l’applet de Connect-AzAccount commande. Par défaut, azure CLI Connect-AzAccount lance le navigateur web par défaut pour authentifier un compte d’utilisateur.

Si l’authentification interactive ne peut pas être prise en charge dans la session, l’argument -UseDeviceAuthentication force l’applet de commande à utiliser un flux d’authentification par code d’appareil à la place, comme l’option correspondante dans les informations d’identification Azure CLI.

S’authentifier via Visual Studio Code

Les développeurs qui utilisent Visual Studio Code peuvent utiliser l’extension de compte Azure pour s’authentifier via l’éditeur. Les applications qui utilisent VisualStudioCodeCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans leur application lors de l’exécution locale.

Pour vous authentifier dans Visual Studio Code, vérifiez que l’extension de compte Azure est installée. Une fois installé, ouvrez la palette de commandes et exécutez la commande Azure : Se connecter .

En outre, utilisez le package de @azure/identity-vscode plug-in. Ce package fournit les dépendances de VisualStudioCodeCredential et l’active. Consultez Plug-ins.

Il s’agit d’un problème connu qui VisualStudioCodeCredential ne fonctionne pas avec les versions d’extension de compte Azure plus récentes que 0.9.11. Une solution à long terme à ce problème est en cours. En attendant, envisagez de vous authentifier via Azure CLI.

Authentifier le client dans les navigateurs

Pour authentifier les clients du Kit de développement logiciel (SDK) Azure dans les navigateurs web, nous proposons le InteractiveBrowserCredential, qui peut être défini pour utiliser la redirection ou des fenêtres contextuelles pour terminer le flux d’authentification. Il est nécessaire de créer d’abord une inscription Azure App dans le Portail Azure de votre application web.

Concepts clés

S’il s’agit de la première fois que vous utilisez @azure/identity ou Microsoft Entra ID, lisez Utiliser @azure/identity avec Microsoft Entra ID d’abord. Ce document fournit une compréhension plus approfondie de la plateforme et de la configuration correcte de votre compte Azure.

Informations d'identification

Les informations d’identification sont une classe qui contient ou peut obtenir les données nécessaires à un client de service pour authentifier les demandes. Les clients de service du Kit de développement logiciel (SDK) Azure acceptent les informations d’identification lorsqu’ils sont construits. Les clients de service utilisent ces informations d’identification pour authentifier les demandes adressées au service.

La bibliothèque Azure Identity se concentre sur l’authentification OAuth avec Microsoft Entra ID et offre diverses classes d’informations d’identification capables d’acquérir un jeton Microsoft Entra pour authentifier les demandes de service. Toutes les classes d’informations d’identification dans cette bibliothèque sont des implémentations de la classe abstraite TokenCredential. Elles peuvent être utilisées pour construire des clients de service capables d’authentifier les demandes au moyen d’un TokenCredential.

Consultez Classes d’informations d’identification.

DefaultAzureCredential

Est DefaultAzureCredential approprié pour la plupart des scénarios où l’application est destinée à être exécutée dans Azure. Cela est dû au fait que le DefaultAzureCredential combine les informations d’identification couramment utilisées pour l’authentification en cas de déploiement avec les informations d’identification utilisées pour l’authentification dans un environnement de développement.

Remarque : DefaultAzureCredential vise à simplifier la prise en main du KIT de développement logiciel (SDK) en gérant des scénarios courants avec des comportements par défaut raisonnables. Les développeurs qui souhaitent davantage de contrôle ou dont le scénario n’est pas pris en charge par les paramètres par défaut doivent utiliser d’autres types d’informations d’identification.

S’il est utilisé à partir de Node.js, le DefaultAzureCredential tente de s’authentifier via les mécanismes suivants dans l’ordre :

1. Environnement : lit les DefaultAzureCredential informations de compte spécifiées via des variables d’environnement et les utilise pour s’authentifier.
2. Identité de charge de travail : si l’application est déployée sur Azure Kubernetes Service avec l’identité managée activée, DefaultAzureCredential s’authentifie avec elle.
3. Identité managée : si l’application est déployée sur un hôte Azure avec l’identité managée activée, le DefaultAzureCredential s’authentifie avec ce compte.
4. Azure CLI : si le développeur a authentifié un compte via la commande Azure CLI az login , s’authentifie DefaultAzureCredential auprès de ce compte.
5. Azure PowerShell : si le développeur s’est authentifié à l’aide de la commande de module Connect-AzAccount Azure PowerShell, le DefaultAzureCredential s’authentifie auprès de ce compte.
6. Azure Developer CLI : si le développeur a authentifié un compte via la commande Azure Developer CLIazd auth login, le DefaultAzureCredential s’authentifie auprès de ce compte.

Stratégie de continuation

À partir de la version 3.3.0, DefaultAzureCredential tente de s’authentifier avec toutes les informations d’identification du développeur jusqu’à ce que l’une d’elles réussisse, quelles que soient les erreurs rencontrées précédemment dans les informations d’identification du développeur. Par exemple, une information d’identification de développeur peut tenter d’obtenir un jeton et échouer. Elle passe donc DefaultAzureCredential aux informations d’identification suivantes dans le flux. Les informations d’identification de service déployées arrêtent le flux avec une exception levée si elles sont en mesure de tenter de récupérer des jetons, mais qu’elles n’en reçoivent pas.

Cela permet d’essayer toutes les informations d’identification du développeur sur votre ordinateur tout en ayant un comportement de déploiement prévisible.

Remarque sur VisualStudioCodeCredential

En raison d’un problème connu, VisualStudioCodeCredential a été supprimé de la chaîne de DefaultAzureCredential jetons. Lorsque le problème est résolu dans une version ultérieure, cette modification est annulée.

Plug-ins

Azure Identity pour JavaScript fournit une API de plug-in qui nous permet de fournir certaines fonctionnalités via des packages de plug-in distincts. Le @azure/identity package exporte une fonction de niveau supérieur (useIdentityPlugin) qui peut être utilisée pour activer un plug-in. Nous fournissons deux packages de plug-ins :

• @azure/identity-broker, qui fournit la prise en charge de l’authentification répartie via un répartiteur natif, tel que le Gestionnaire de comptes web.
• @azure/identity-cache-persistence, qui fournit une mise en cache persistante des jetons dans Node.js à l’aide d’un système de stockage sécurisé natif fourni par votre système d’exploitation. Ce plug-in permet aux valeurs mises en access_token cache de persister entre les sessions, ce qui signifie qu’un flux de connexion interactif n’a pas besoin d’être répété tant qu’un jeton mis en cache est disponible.

Exemples

D’autres exemples d’utilisation des différentes informations d’identification sont fournis dans la page Exemples Azure Identity

Authentifiez-vous avec le DefaultAzureCredential

Cet exemple illustre l’authentification du KeyClient à partir de la bibliothèque cliente @azure/keyvault-keys à l’aide de 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);

Spécifier une identité managée affectée par l’utilisateur avec le DefaultAzureCredential

Un scénario relativement courant implique l’authentification à l’aide d’une identité managée affectée par l’utilisateur pour une ressource Azure. Explorez l’exemple d’authentification d’une identité managée affectée par l’utilisateur avec DefaultAzureCredential pour voir comment cette tâche est relativement simple qui peut être configurée à l’aide de variables d’environnement ou dans du code.

Définir un flux d’authentification personnalisé avec les ChainedTokenCredential

L’utilisation des DefaultAzureCredential est généralement le moyen le plus rapide pour commencer à développer des applications pour Azure, mais les utilisateurs plus expérimentés souhaiteront peut-être personnaliser les informations d’identification prises en compte lors de l’authentification. Avec ChainedTokenCredential, les utilisateurs peuvent combiner plusieurs instances d’informations d’identification pour définir une chaîne d’informations d’identification personnalisée. Cet exemple illustre la création d’un ChainedTokenCredential qui tente de s’authentifier à l’aide de deux instances configurées différemment de ClientSecretCredential, pour ensuite authentifier à KeyClient partir du @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);

Prise en charge des identités managées

L’authentification d’identité managée est prise en charge via les DefaultAzureCredential classes d’informations d’identification ou ManagedIdentityCredential directement pour les services Azure suivants :

• Azure App Service et Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Machines virtuelles Azure
• Azure Virtual Machine Scale Sets

Pour obtenir des exemples d’utilisation de l’identité managée pour l’authentification, consultez les exemples.

Cloud configuration

Par défaut, les informations d’identification s’authentifient auprès du point de terminaison Microsoft Entra pour le cloud public Azure. Pour accéder aux ressources d’autres clouds, telles que Azure Government ou un cloud privé, configurez les informations d’identification avec l’argument authorityHost dans le constructeur. L’interface AzureAuthorityHosts définit les autorités pour les clouds connus. Pour le cloud US Government, vous pouvez instancier des informations d’identification de cette façon :

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

Toutes les informations d’identification ne nécessitent pas cette configuration. Les informations d’identification qui s’authentifient via un outil de développement, tel que AzureCliCredential, utilisent la configuration de cet outil. De même, VisualStudioCodeCredential accepte un authorityHost argument, mais utilise par défaut le authorityHost paramètre Azure : Cloud de Visual Studio Code correspondant.

Classes d’informations d’identification

Authentifier les applications hébergées par Azure

Informations d'identification	Usage	Exemple
DefaultAzureCredential	Fournit une expérience d’authentification simplifiée pour commencer rapidement à développer des applications exécutées dans Azure.	Exemple
ChainedTokenCredential	Permet aux utilisateurs de définir des flux d’authentification personnalisés qui se composent de plusieurs informations d’identification.	Exemple
EnvironmentCredential	Authentifie un principal de service ou un utilisateur via les informations d’identification spécifiées dans les variables d’environnement.	Exemple
ManagedIdentityCredential	Authentifie l’identité managée d’une ressource Azure.	Exemple
WorkloadIdentityCredential	Prend en charge ID de charge de travail Microsoft Entra sur Kubernetes.	Exemple

Authentifier les principaux de service

Informations d'identification	Usage	Exemple	Référence
ClientAssertionCredential	Authentifie un principal de service à l’aide d’une assertion cliente signée.	Exemple	Authentification d’un principal du service
ClientCertificateCredential	Authentifie un principal de service à l’aide d’un certificat.	Exemple	Authentification d’un principal du service
ClientSecretCredential	Authentifie un principal de service à l’aide d’un secret.	Exemple	Authentification d’un principal du service

Authentification des utilisateurs

Informations d'identification	Usage	Exemple	Référence
AuthorizationCodeCredential	Authentifie un utilisateur avec un code d’autorisation obtenu précédemment.	Exemple	Code d’authentification OAuth2
DeviceCodeCredential	Authentifie un utilisateur de manière interactive sur les appareils ayant une interface utilisateur limitée.	Exemple	Authentification de code d’appareil
InteractiveBrowserCredential	Authentifie un utilisateur de manière interactive avec le navigateur système par défaut. Apprenez-en davantage ici sur le fonctionnement.	Exemple	Code d’authentification OAuth2
OnBehalfOfCredential	Propage l’identité et les autorisations de l’utilisateur délégué par le biais de la chaîne de demandes		Authentification de la part de
UsernamePasswordCredential	Authentifie un utilisateur au moyen d’un nom d’utilisateur et d’un mot de passe.	Exemple	Authentification par nom d'utilisateur et mot de passe

S’authentifier via des outils de développement

Informations d'identification	Usage	Exemple	Référence
AzureCliCredential	Permet l’authentification dans un environnement de développement avec Azure CLI.	Exemple	Authentification Azure CLI
AzureDeveloperCliCredential	Authentifiez-vous dans un environnement de développement avec l’utilisateur ou le principal de service activé dans Azure Developer CLI.		référence Azure Developer CLI
AzurePowerShellCredential	Authentifiez-vous dans un environnement de développement à l’aide de Azure PowerShell.	Exemple	Authentification Azure PowerShell
VisualStudioCodeCredential	S’authentifie en tant qu’utilisateur connecté à l’extension de compte Azure Visual Studio Code.		Extension de compte Azure VS Code

Variables d'environnement

Les DefaultAzureCredential et EnvironmentCredential peuvent être configurés à l’aide de variables d’environnement. Chaque type d’authentification nécessite des valeurs pour des variables spécifiques.

Principal de service avec une clé secrète

Nom de la variable	Valeur
AZURE_CLIENT_ID	ID d’une application Microsoft Entra
AZURE_TENANT_ID	ID du locataire Microsoft Entra de l’application
AZURE_CLIENT_SECRET	un des secrets client de l’application

Principal de service avec un certificat

Nom de la variable	Valeur
AZURE_CLIENT_ID	ID d’une application Microsoft Entra
AZURE_TENANT_ID	ID du locataire Microsoft Entra de l’application
AZURE_CLIENT_CERTIFICATE_PATH	chemin d’accès à un fichier de certificat encodé pem, y compris la clé privée
AZURE_CLIENT_CERTIFICATE_PASSWORD	mot de passe du fichier de certificat, le cas échéant

Nom d’utilisateur et mot de passe

Nom de la variable	Valeur
AZURE_CLIENT_ID	ID d’une application Microsoft Entra
AZURE_TENANT_ID	ID du locataire Microsoft Entra de l’application
AZURE_USERNAME	nom d’utilisateur (généralement une adresse e-mail)
AZURE_PASSWORD	mot de passe de cet utilisateur

La configuration est tentée dans l’ordre indiqué ci-dessus. Par exemple, si les valeurs d’un certificat et d’une clé secrète client sont toutes deux présentes, la clé secrète client est utilisée.

Évaluation continue de l’accès

À partir de la version 3.3.0, l’accès aux ressources protégées par l’évaluation continue de l’accès (CAE) est possible par demande. Cela peut être activé à l’aide de l’APIGetTokenOptions.enableCae(boolean). CAE n’est pas pris en charge pour les informations d’identification des développeurs.

Mise en cache de jeton

La mise en cache de jetons est une fonctionnalité fournie par la bibliothèque Azure Identity qui permet aux applications de :

• Cachez les jetons en mémoire (par défaut) et sur le disque (opt-in).
• Améliorez la résilience et les performances.
• Réduisez le nombre de demandes adressées à Microsoft Entra ID pour obtenir des jetons d’accès.

La bibliothèque Azure Identity offre à la fois une mise en cache de disque en mémoire et persistante. Pour plus d’informations, consultez la documentation relative à la mise en cache des jetons.

Authentification répartie

Un répartiteur d’authentification est une application qui s’exécute sur l’ordinateur d’un utilisateur et gère les liaisons d’authentification et la maintenance des jetons pour les comptes connectés. Actuellement, seul le Gestionnaire de comptes web Windows (WAM) est pris en charge. Pour activer la prise en charge, utilisez le @azure/identity-broker package. Pour plus d’informations sur l’authentification à l’aide de WAM, consultez la documentation du plug-in broker.

Dépannage

Pour obtenir de l’aide sur la résolution des problèmes, consultez le guide de résolution des problèmes.

Étapes suivantes

Lisez la documentation

La documentation de l’API pour cette bibliothèque est disponible sur notre site de documentation.

Prise en charge de la bibliothèque de client

Les bibliothèques clientes et de gestion répertoriées sur la page versions du Kit de développement logiciel (SDK) Azure qui prennent en charge Microsoft Entra l’authentification acceptent les informations d’identification de cette bibliothèque. En savoir plus sur l’utilisation de ces bibliothèques dans leur documentation, qui est liée à partir de la page des versions.

Problèmes connus

Prise en charge d’Azure Active Directory B2C

Cette bibliothèque ne prend pas en charge le service Azure AD B2C .

Pour d’autres problèmes ouverts, consultez le dépôt GitHub de la bibliothèque.

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.