Bibliothèque de client Azure Identity pour JavaScript - version 4.4.1
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
- documentation Microsoft Entra ID
- Exemples
Commencer
Environnements actuellement pris en charge
-
versions LTS de Node.js
-
Remarque : Si votre application s’exécute sur Node.js v8 ou version inférieure et que vous ne pouvez pas mettre à niveau votre version Node.js vers la dernière version stable, épinglez votre dépendance
@azure/identity
à la version 1.1.0.
-
Remarque : Si votre application s’exécute sur Node.js v8 ou version inférieure et que vous ne pouvez pas mettre à niveau votre version Node.js vers la dernière version stable, épinglez votre dépendance
- 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.
-
Remarque: parmi les différentes informations d’identification exportées dans cette bibliothèque,
Pour plus d’informations, consultez notre de 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>
fonctionnera 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 bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) directement. 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
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 de l’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 du Azure CLI utilisateurs peuvent exécuter la commande az login
. 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.
Pour les systèmes sans navigateur web par défaut, la commande az login
utilise le flux d’authentification du code de l’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
.
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 auprès utilisateurs d’Azure PowerShell pouvez exécuter 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.
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
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 pour qu’un client de service authentifie 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 une variété de 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 d’s’authentifier auprès d’un TokenCredential.
Consultez classes d’informations d’identification.
DefaultAzureCredential
Le DefaultAzureCredential
convient à 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 s’authentifier lorsqu’elles sont déployées avec des informations d’identification utilisées pour s’authentifier 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 plus de contrôle ou dont le scénario n’est pas servi par les paramètres par défaut doivent utiliser d’autres types d’informations d’identification.
Si elle est utilisée à partir de Node.js, l'DefaultAzureCredential
tente de s’authentifier via les mécanismes suivants dans l’ordre :
-
Environnement : le
DefaultAzureCredential
lit les informations de compte spécifiées via variables d’environnement et l’utiliser pour l’authentification. -
l’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. -
Managed Identity : si l’application est déployée sur un hôte Azure avec l’identité managée activée, le
DefaultAzureCredential
s’authentifie auprès de ce compte. -
Azure CLI : si le développeur a authentifié un compte via la commande
az login
Azure CLI, leDefaultAzureCredential
s’authentifie auprès de ce compte. -
Azure PowerShell : si le développeur s’est authentifié à l’aide de la commande
Connect-AzAccount
module Azure PowerShell, leDefaultAzureCredential
s’authentifie avec ce compte. -
azure Developer CLI : si le développeur a authentifié un compte via la commande
azd auth login
Azure Developer CLI, leDefaultAzureCredential
s’authentifie avec ce compte.
Stratégie de continuation
À compter de la version 3.3.0, DefaultAzureCredential
tentera de s’authentifier auprès de 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 deaccess_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 auprès du DefaultAzureCredential
Cet exemple illustre l’authentification du KeyClient
à partir de la bibliothèque cliente @azure/keyvault-keys à l’aide de la 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 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 le ChainedTokenCredential
Bien que le 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 tentera de s’authentifier à l’aide de deux instances configurées différemment de ClientSecretCredential
, puis authentifiez l'KeyClient
à partir des @azure/clés de coffre de clés:
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 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’interface 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 { 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 argument authorityHost
, mais correspond par défaut au paramètre authorityHost
Azure de Visual Studio Code : Cloud.
Classes d’informations d’identification
Authentifier des applications hébergées par Azure
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 |
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 |
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 |
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 ci-dessus. Par exemple, si les valeurs d’une clé secrète client et d’un certificat sont 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
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.
Azure SDK for JavaScript