Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
La bibliothèque Azure Identity fournit des credentials : les classes publiques qui implémentent l'interface Azure Core library TokenCredential. Les informations d’identification représentent un flux d’authentification distinct pour l’acquisition d’un jeton d’accès à partir de 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.
Diagramme montrant la séquence de la chaîne d’identifiants.
Pourquoi utiliser des chaînes d’informations d’identification
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 com.azure.core.credential.TokenCredential; import com.azure.identity.AzureCliCredentialBuilder; import com.azure.identity.ManagedIdentityCredentialBuilder; // Code omitted for brevity TokenCredential credential = null; // Set up credential based on environment (Azure or local development) String environment = System.getenv("ENV"); if (environment != null && environment.equals("production")) { credential = new ManagedIdentityCredentialBuilder() .clientId(userAssignedClientId) .build(); } else { credential = new AzureCliCredentialBuilder() .build(); }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 des informations d’identification chaînées
Il existe deux approches différentes pour le chaînage des informations d'identification :
- Utilisez une chaîne préconfigurée : commencez par une chaîne préconstruite et structurée qui s’adapte aux scénarios d’authentification les plus courants. 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.
Présentation 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 :
Diagramme montrant le flux d’authentification DefaultAzureCredential.
L'ordre dans lequel tente les informations d’identification est le suivant.
| JSON | Informations d'identification | Descriptif |
|---|---|---|
| 1 | Environnement | Lit une collection de variables environment pour déterminer si un principal de service d’application (utilisateur d’application) est configuré pour l’application. Dans ce cas, DefaultAzureCredential utilise ces valeurs pour authentifier l’application à Azure. Cette méthode peut être utilisée lors du développement localement, mais elle est la plus souvent utilisée dans les environnements serveur. |
| 2 | Identité de charge de travail | Si l’application est déployée sur un hôte Azure avec l’identité de charge de travail activée, authentifiez ce compte. |
| 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 pour Azure à l’aide de cette identité managée. |
| 4 | IntelliJ | Si le développeur s’est authentifié via Azure Toolkit pour IntelliJ, authentifiez ce compte. |
| 5 | Visual Studio Code | Si le développeur s'est authentifié via l'extension Azure Resources de Visual Studio Code et que le package azure-identity-broker est installé, authentifiez ce compte. |
| 6 | Azure CLI | Si le développeur s'est authentifié pour Azure à l'aide de la commande az login de Azure CLI, authentifiez l'application pour Azure à l'aide de ce même compte. |
| 7 | Azure PowerShell | Si le développeur s'est authentifié pour Azure à l'aide de l'applet de commande Connect-AzAccount de Azure PowerShell, authentifiez l'application pour Azure à l'aide de ce même compte. |
| 8 | Azure Developer CLI | Si le développeur s'est authentifié à Azure à l'aide de la commande azd auth login du Azure Developer CLI, authentifiez-vous avec ce compte. |
| 9 | Broker | Authentifie en utilisant le compte par défaut connecté au système d'exploitation via un intermédiaire. Exige que le package azure-identity-broker soit installé, puisqu'une instance activée par un broker de est utilisée. |
Dans sa forme la plus simple, vous pouvez utiliser la version sans paramètre de comme suit :
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
// Code omitted for brevity
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.build();
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 ou , définissez la variable d'environnement sur ou , respectivement. Lorsqu’une valeur est utilisée, la chaîne d’informations d’identification sous-jacente se présente comme suit :
Diagramme montrant DefaultAzureCredential avec AZURE_TOKEN_CREDENTIALS défini sur « prod ».
Lorsqu’une valeur est utilisée, la chaîne se présente comme suit :
Diagramme montrant DefaultAzureCredential avec AZURE_TOKEN_CREDENTIALS défini sur « dev ».
Importante
La variable d’environnement est prise en charge dans les versions de package 1.16.1 et ultérieures.
Pour vous assurer que la variable d’environnement est configurée sur une chaîne validée, appelez la méthode comme suit :
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
.build();
Importante
La méthode est disponible dans les versions de package 1.18.0 et ultérieures.
Pour utiliser un nom de variable d’environnement personnalisé au lieu de la valeur par défaut , utilisez pour créer une référence à votre variable personnalisée :
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
.build();
Note
La méthode lève une valeur si les variables d’environnement spécifiées ne sont pas définies ou sont vides.
Utiliser des informations d’identification spécifiques
Pour exclure toutes les informations d’identification à l’exception d’une, définissez la variable d’environnement sur le nom des informations d’identification. Par exemple, vous pouvez réduire la chaîne en définissant sur . 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 :
AzureCliCredentialAzureDeveloperCliCredentialAzurePowerShellCredentialEnvironmentCredentialIntelliJCredentialManagedIdentityCredentialVisualStudioCodeCredentialWorkloadIdentityCredential
Importante
La variable d’environnement prend en charge les noms d’informations d’identification individuels dans les versions 1.17.0 et ultérieures du package.
Pour vous assurer que la variable d’environnement est définie avec une chaîne prise en charge, appelez la méthode requireEnvVars comme suit :
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
.build();
Présentation 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 com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;
// Code omitted for brevity
AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
.build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
.build();
ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
.addLast(cliCredential)
.addLast(ijCredential)
.build();
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. est tentée en premier, suivie de , si nécessaire. Sous forme graphique, la chaîne ressemble à ceci :
Conseil
Pour améliorer les performances, optimisez l’ordre des informations d’identification dans 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 commencer avec la bibliothèque d’identité Azure, mais avec cette commodité vient les compromis. Après avoir déployé votre application sur Azure, vous devez comprendre les exigences d'authentification de l'application et déterminer si DefaultAzureCredential convient à votre scénario.
offre un avantage clé : il dissocie votre code d’application à partir de mécanismes d’authentification spécifiques, ce qui vous permet de modifier votre configuration d’authentification sans modifier le code. Pour les développeurs expérimentés qui configurent consciemment leur authentification de production, cette flexibilité peut être utile. Toutefois, cette flexibilité présente des inconvénients potentiels :
- 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 la journalisation pour voir la progression d’une information d’identification à l’autre et l’état de réussite/échec de chacun d’entre elles. Pour plus d’informations, consultez Déboguer des identifiants chaînés.
- 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, échoue toujours dans l’environnement de développement local.
-
Comportement non prévisible :
DefaultAzureCredentialvérifie la présence de certaines variables environment. 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 au moment de l’exécution dans n’importe quelle application s’exécutant sur cet ordinateur. - Discordances de permissions : s’arrête au premier identifiant qui acquiert un jeton, qu'il dispose ou non des autorisations appropriées. Par exemple, les identifiants de développement local peuvent avoir des autorisations plus larges que l'identité managée de production, ce qui permet à l'application de fonctionner localement, mais fait échouer les vérifications d’autorisation après le déploiement.
Déboguer des informations d’identification chaînées
Pour diagnostiquer un problème inattendu ou comprendre ce que font les informations d’identification chaînées, activez la journalisation dans votre application.
À des fins d’illustration, supposons que la forme sans paramètre de DefaultAzureCredential est utilisée pour authentifier une demande auprès d’un compte Stockage Blob. L’application s’exécute dans l’environnement de développement local et le développeur s’est authentifié pour Azure à l’aide du Azure CLI. Lorsque l’application est exécutée, les entrées pertinentes suivantes apparaissent dans la sortie :
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token
Dans la sortie précédente, vous pouvez voir que :
-
EnvironmentCredential,WorkloadIdentityCredential,ManagedIdentityCredential,IntelliJCredentialetVisualStudioCodeCredentialchacun n’a pas pu acquérir un jeton d’accès Microsoft Entra, dans cet ordre. - L’appel de réussit, comme indiqué par l’entrée suffixée par . Étant donné que a réussi, aucune autre information d’identification n’a été essayée.