Chaînes d’identifiants dans la bibliothèque cliente Azure Identity pour Java

Article
11/12/2024

La bibliothèque cliente Azure Identity fournit des identifiants, des classes publiques qui implémentent l’interface TokenCredential de la bibliothèque Azure Core. Les informations d’identification représentent un flux d’authentification distinct pour l’acquisition d’un jeton d’accès à partir de l’ID Microsoft Entra. 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 informations d’identification chaînées 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 philosophies 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 :

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

Ordre	Informations d'identification	Description
1	Environment	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.
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.
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.
4	Cache partagé de jetons	Si le développeur s’est authentifié auprès d’Azure en se connectant à Visual Studio, authentifiez l’application auprès d’Azure en utilisant ce même compte. (Windows uniquement.)
5	IntelliJ	Si le développeur s’est authentifié via Azure Toolkit pour IntelliJ, authentifiez ce compte.
6	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.
7	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.
8	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.

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

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .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.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Code omitted for brevity

ManagedIdentityCredential miCredential = new ManagedIdentityCredentialBuilder()
    .clientId(userAssignedClientId)
    .build();
AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(miCredential)
    .addLast(cliCredential)
    .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. La variante d’identité managée de ManagedIdentityCredential affectée par l’utilisateur est tentée en premier, suivie de AzureCliCredential, si nécessaire. Sous forme graphique, la chaîne ressemble à ceci :

Diagramme montrant le flux d’authentification pour une instance de ChainedTokenCredential composée d’informations d’identification d’identité managée et d’informations d’identification Azure CLI.

Conseil

Pour améliorer les performances, optimisez l’ordre des informations d’identification dans ChainedTokenCredential pour votre environnement de production. Les informations d’identification destinées à être utilisées dans l’environnement de développement local doivent être ajoutées en dernier.

Conseils d’utilisation pour DefaultAzureCredential

DefaultAzureCredential est sans aucun doute la manière la plus simple de commencer avec la bibliothèque cliente Azure Identity, mais cette commodité comporte 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, vous devez sérieusement envisager de passer de DefaultAzureCredential à l’une des solutions suivantes :

Une implémentation spécifique d’informations d’identification, telle que ManagedIdentityCredential.
Une implémentation de ChainedTokenCredential simplifiée et optimisée pour l’environnement Azure dans lequel votre application s’exécute.

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 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 informations d’identification chaînées.
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 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 soit utilisée pour authentifier une requête à un compte Blob Storage. L’application s’exécute dans l’environnement de développement local, et le développeur s’est authentifié sur Azure à l’aide de l’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 SharedTokenCacheCredential 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 AzureCliCredential returns a token

Dans la sortie précédente, vous pouvez voir que :

EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, SharedTokenCacheCredential et IntelliJCredential n’ont chacun pas réussi à acquérir un jeton d’accès Microsoft Entra, dans cet ordre.
L’appel de AzureCliCredential.getToken réussit, comme indiqué par l’entrée suffixée par returns a token. Étant donné que AzureCliCredential a réussi, aucune autre information d’identification n’a été essayée.

Partager via