Bibliothèque de client Azure Identity pour JavaScript - version 4.5.0

Article
10/17/2024

La bibliothèque d’identités Azure fournit microsoft Entra ID (anciennement l’authentification par jeton Azure Active Directory) via un ensemble d’implémentations pratiques TokenCredential.

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

Liens clés :

code source
package (npm)
Documentation de référence de l’API
Microsoft Entra Documents d’identité
Exemples

Commencer

Environnements actuellement pris en charge

versions LTS de Node.js
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 prise en charge dans le navigateur.

Pour plus d’informations, consultez notre stratégie de support .

Installer le package

Installez Azure Identity avec npm:

npm install --save @azure/identity

Conditions préalables

Un abonnement Azure .
Facultatif : l'Azure CLI et/ou Azure PowerShell peut également être utile 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 se concentrent 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 avons pour objectif de simplifier et de prendre en charge raisonnable les 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 de MSAL.js v2, qui utilisent flux de code d’autorisation OAuth 2.0 avec PKCE et sont compatibles OpenID. Bien que @azure/identity se concentre sur la simplicité, les bibliothèques MSAL.js, telles que @azure/msal-common, @azure/msal-nodeet @azure/msal-browser, sont conçues pour fournir une prise en charge robuste des protocoles d’authentification pris en charge par Azure.

Quand utiliser un autre élément

Les types d’informations d’identification @azure/identity sont des implémentations de @azure/authentification principaleclasse TokenCredential. En principe, tout objet avec une méthode getToken qui satisfait getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> fonctionne en tant que 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 scénarios avancés, les développeurs peuvent utiliser bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) directement à la place. Envisagez d’utiliser MSAL.js dans les scénarios suivants :

Développeurs qui souhaitent contrôler entièrement le protocole d’authentification et sa configuration.
Nos types d’informations d’identification sont conçus pour être utilisés avec les clients du Kit de développement logiciel (SDK) Azure avec la mise en cache intelligente et l’actualisation des jetons gérées au niveau de la couche HTTP principale. Si vous vous trouvez obligé d’utiliser getToken directement, vous pouvez tirer parti de l’utilisation de MSAL.js pour plus de contrôle sur le flux d’authentification et la mise en cache des jetons.

Vous pouvez en savoir plus sur les liens suivants :

Nous décrivons certains cas d’usage avancés de @azure/identity sur la page Exemples d’identité Azure.
- Nous disposons spécifiquement d’une section Exemples avancés.
- Nous avons également une section qui montre comment s’authentifier avec MSAL directement.

Pour les flux de travail d’authentification avancés 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

Bien que nous vous recommandons d’utiliser l’identité managée dans votre application hébergée par Azure, il est courant qu’un développeur utilise son propre compte pour authentifier les appels aux services Azure lors du débogage et de l’exécution de code localement. Il existe plusieurs outils de développement qui peuvent être utilisés pour effectuer cette authentification dans votre environnement de développement.

S’authentifier via Azure Developer CLI

Les développeurs qui codent en dehors d’un IDE peuvent également utiliser les Azure Developer CLI pour s’authentifier. Les applications utilisant le DefaultAzureCredential ou le AzureDeveloperCliCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans leur application lors de l’exécution locale.

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

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

S’authentifier via Azure CLI

Les applications utilisant le AzureCliCredential, que ce soit directement ou via le DefaultAzureCredential, peuvent utiliser le compte Azure CLI pour authentifier les appels dans l’application lors de l’exécution localement.

Pour vous authentifier auprès duAzure CLI , exécutez la commande . Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut, Azure CLI lance le navigateur pour authentifier l’utilisateur.

connexion au compte Azure CLI

Pour les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification du code d’appareil. L’utilisateur peut également forcer Azure CLI à utiliser le flux de code de l’appareil plutôt que de lancer un navigateur en spécifiant l’argument --use-device-code.

connexion au code d’appareil du compte Azure CLI

S’authentifier via Azure PowerShell

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

Pour vous authentifier avec Azure PowerShell, exécutez l’applet de commande Connect-AzAccount. Par défaut, comme Azure CLI, Connect-AzAccount lance le navigateur web par défaut pour authentifier un compte d’utilisateur.

connexion au compte Azure PowerShell

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 de code d’appareil, similaire à l’option correspondante dans les informations d’identification Azure CLI.

S’authentifier via Visual Studio Code

Les développeurs utilisant Visual Studio Code peuvent utiliser l’extension de compte Azure pour s’authentifier via l’éditeur. Les applications utilisant 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 plug-in @azure/identity-vscode. Ce package fournit les dépendances de VisualStudioCodeCredential et l’active. Consultez plug-ins.

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

Authentifier le client dans les navigateurs

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

Concepts clés

S’il s’agit de votre première utilisation de @azure/identity ou de l’ID Microsoft Entra, lisez d’abord Utilisation de @azure/identity avec l’ID Microsoft Entra. Ce document fournit une compréhension plus approfondie de la plateforme et de la façon de configurer correctement votre compte Azure.

Pouvoirs

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 dans le 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 auprès du service.

La bibliothèque d’identités Azure se concentre sur l’authentification OAuth avec l’ID Microsoft Entra et offre différentes 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 de cette bibliothèque sont des implémentations de la classe abstraite TokenCredential, et l’une d’elles peut être utilisée pour construire des clients de service capables de s’authentifier auprès d’un TokenCredential.

Consultez classes d’informations d’identification.

DefaultAzureCredential

DefaultAzureCredential simplifie l’authentification lors du développement d’applications déployées sur Azure en combinant les informations d’identification utilisées dans les environnements d’hébergement Azure avec les informations d’identification utilisées dans le développement local. Pour plus d’informations, consultez la vue d’ensemble de DefaultAzureCredential.

Stratégie de continuation

À compter de la version 3.3.0, DefaultAzureCredential tente de s’authentifier avec toutes les informations d’identification du développeur jusqu’à ce qu’elles réussissent, quelles que soient les erreurs rencontrées par les informations d’identification des développeurs précédentes. Par exemple, les informations d’identification d’un développeur peuvent tenter d’obtenir un jeton et d’échouer. Par conséquent, DefaultAzureCredential passe aux informations d’identification suivantes dans le flux. Les informations d’identification du service déployées arrêtent le flux avec une exception levée s’ils sont en mesure de tenter la récupération de jeton, mais ne en reçoivent pas.

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

Remarque sur `VisualStudioCodeCredential`

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

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 package @azure/identity exporte une fonction de niveau supérieur (useIdentityPlugin) qui peut être utilisée pour activer un plug-in. Nous fournissons deux packages de plug-in :

@azure/identity-broker, qui fournit une prise en charge de l’authentification répartie par le biais d’un répartiteur natif, tel que le Gestionnaire de comptes web.
@azure/identity-cache-persistence, qui fournit une mise en cache de jetons persistante 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 de conserver les valeurs de access_token mises en cache 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

Vous trouverez d’autres exemples d’utilisation de différentes informations d’identification dans page Exemples d’identité Azure

S’authentifier avec `DefaultAzureCredential`

Cet exemple illustre l’authentification du KeyClient à partir de la bibliothèque cliente @azure/keyvault-keys à l’aide de DefaultAzureCredential.

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

Spécifier une identité managée affectée par l’utilisateur avec `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 sur l’authentification d’une identité managée affectée par l’utilisateur avec DefaultAzureCredential pour voir comment cela est rendu une tâche 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 `ChainedTokenCredential`

Bien que DefaultAzureCredential soit généralement le moyen le plus rapide de commencer à développer des applications pour Azure, les utilisateurs plus avancés peuvent souhaiter personnaliser les informations d’identification prises en compte lors de l’authentification. Le ChainedTokenCredential permet aux utilisateurs de combiner plusieurs instances d’informations d’identification pour définir une chaîne personnalisée d’informations d’identification. 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 authentifier ensuite l'KeyClient à partir des @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);

Prise en charge des identités managées

L’authentification d’identité managée est prise en charge via les classes d’informations d’identification DefaultAzureCredential 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
groupes de machines virtuelles identiques Azure

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

Configuration cloud

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

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

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

En guise d’alternative à la spécification de l’argument authorityHost, vous pouvez également définir la variable d’environnement AZURE_AUTHORITY_HOST sur l’URL de l’autorité de votre cloud. Cette approche est utile lors de la configuration de plusieurs informations d’identification pour s’authentifier sur le même cloud ou lorsque l’environnement déployé doit définir le cloud cible :

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

L’énumération AzureAuthorityHosts définit les autorités pour les clouds connus pour votre commodité ; Toutefois, si l’autorité de votre cloud n’est pas répertoriée dans AzureAuthorityHosts, vous pouvez passer n’importe quelle URL d’autorité valide en tant qu’argument de chaîne. Par exemple :

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

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

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 argument authorityHost, mais correspond par défaut au paramètre authorityHostAzure de Visual Studio Code : Cloud.

Classes d’informations d’identification

Chaînes d’informations d’identification

Credential	Usage	Exemple
`DefaultAzureCredential`	Fournit une expérience d’authentification simplifiée pour commencer rapidement à développer des applications exécutées dans Azure.	exemple de
`ChainedTokenCredential`	Permet aux utilisateurs de définir des flux d’authentification personnalisés qui composent plusieurs informations d’identification.	exemple de

Authentifier des applications hébergées par Azure

Credential	Usage	Exemple
`EnvironmentCredential`	Authentifie un principal de service ou un utilisateur via des informations d’identification spécifiées dans les variables d’environnement.	exemple de
`ManagedIdentityCredential`	Authentifie l’identité managée d’une ressource Azure.	exemple de
`WorkloadIdentityCredential`	Prend en charge ID de charge de travail Microsoft Entra sur Kubernetes.	exemple de

Authentifier les principaux de service

Credential	Usage	Exemple	Référence
`AzurePipelinesCredential`	Prend en charge ID de charge de travail Microsoft Entra sur Azure Pipelines.	exemple de
`ClientAssertionCredential`	Authentifie un principal de service à l’aide d’une assertion de client signée.	exemple de	d’authentification du principal de service
`ClientCertificateCredential`	Authentifie un principal de service à l’aide d’un certificat.	exemple de	d’authentification du principal de service
`ClientSecretCredential`	Authentifie un principal de service à l’aide d’un secret.	exemple de	d’authentification du principal de service

Authentifier les utilisateurs

Credential	Usage	Exemple	Référence
`AuthorizationCodeCredential`	Authentifie un utilisateur avec un code d’autorisation précédemment obtenu.	exemple de	code d’authentification OAuth2
`DeviceCodeCredential`	Authentifie de manière interactive un utilisateur sur des appareils avec une interface utilisateur limitée.	exemple de	d’authentification du code d’appareil
`InteractiveBrowserCredential`	Authentifie de manière interactive un utilisateur avec le navigateur système par défaut. En savoir plus sur la façon dont cela se produit ici.	exemple de	code d’authentification OAuth2
`OnBehalfOfCredential`	Propage l’identité et les autorisations de l’utilisateur délégué via la chaîne de requêtes		d’authentification au nom
`UsernamePasswordCredential`	Authentifie un utilisateur avec un nom d’utilisateur et un mot de passe.	exemple de	nom d’utilisateur + authentification par mot de passe

S’authentifier via des outils de développement

Credential	Usage	Exemple	Référence
`AzureCliCredential`	Authentifiez-vous dans un environnement de développement avec Azure CLI.	exemple de	d’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.		informations de référence sur l’interface CLI pour développeurs Azure
`AzurePowerShellCredential`	Authentifiez-vous dans un environnement de développement à l’aide d’Azure PowerShell.	exemple de	d’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

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

Principal de service avec secret

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`	l’un des secrets clients de l’application

Principal de service avec 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 une clé privée
`AZURE_CLIENT_CERTIFICATE_PASSWORD`	(facultatif) mot de passe du fichier de certificat, le cas échéant
`AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`	(facultatif) envoyer une chaîne de certificats dans l’en-tête x5c pour prendre en charge l’authentification basée sur le sujet/ l’authentification basée sur l’émetteur

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`	un 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 précédent. Par exemple, si les valeurs d’un certificat et d’une clé secrète client sont toutes les deux présentes, la clé secrète client est utilisée.

Évaluation continue de l’accès

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

Mise en cache des jetons

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

Jetons de cache en mémoire (valeur par défaut) et sur 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 d’identités Azure offre à la fois la mise en cache en mémoire et les disques persistants. Pour plus d’informations, consultez la documentation de 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 package @azure/identity-broker. 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

Lire la documentation

Vous trouverez la documentation de l’API pour cette bibliothèque sur notre site de documentation .

Prise en charge de la bibliothèque cliente

Les bibliothèques de client et de gestion répertoriées dans la page kit de développement logiciel (SDK) Azure qui prennent en charge l’authentification Microsoft Entra 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 AD 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 que vous avez des suggestions, ouvrez un problème.

Contribuant

Pour contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la création et le test du code.

Impressions

Partager via