Chaînes d’informations d’identification dans la bibliothèque Azure Identity pour Python

La bibliothèque Azure Identity fournit des informations d’identification , des classes publiques qui implémentent le protocole 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.

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 :

  # Set up credential based on environment (Azure or local development)
  if os.getenv("WEBSITE_HOSTNAME"):
      credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
  else:
      credential = AzureCliCredential()
  

• 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 :

• « Démonter » une chaîne : commencez par une chaîne préconfigurée et excluez ce dont vous n’avez pas besoin. 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	Descriptif	Activée par défaut ?
1	Environnement	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.	Oui
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.	Oui
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.	Oui
4	Cache partagé de jetons	Sur Windows uniquement, si le développeur s’est authentifié auprès d’Azure en se connectant à Visual Studio, authentifiez l’application auprès d’Azure à l’aide de ce même compte.	Oui
5	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.	Oui
6	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.	Oui
7	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.	Oui
8	Navigateur interactif	Si cette option est activée, authentifiez le développeur de manière interactive via le navigateur par défaut du système actuel.	Non

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Acquire a credential object
credential = DefaultAzureCredential()

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential
)

Comment personnaliser DefaultAzureCredential

Les sections suivantes décrivent les stratégies d’omission des informations d’identification de la chaîne.

Exclure des informations d’identification individuelles

Pour exclure des informations d’identification individuelles à partir de DefaultAzureCredential, utilisez le paramètre de exclude avec le préfixe correspondant. Par exemple :

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Dans l’exemple de code précédent, EnvironmentCredential et WorkloadIdentityCredential sont supprimés de la chaîne d’informations d’identification. Par conséquent, les premières informations d’identification à tenter sont ManagedIdentityCredential. La chaîne modifiée ressemble à ceci :

Remarque

InteractiveBrowserCredential est exclu par défaut et n’est donc pas affiché dans le diagramme précédent. Pour inclure InteractiveBrowserCredential, définissez le paramètre exclude_interactive_browser_credential à False lors de l’appel du constructeur DefaultAzureCredential.

À mesure que davantage de paramètres de mot-clé avec le préfixe exclude sont définis sur True (des exclusions d’informations d’identification sont configurées), les avantages de l’utilisation de DefaultAzureCredential diminuent. Dans ce cas, ChainedTokenCredential est un meilleur choix et nécessite moins de code. Pour illustrer ceci, ces deux exemples de code se comportent de la même façon :

DefaultAzureCredential

credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

ChainedTokenCredential

credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id=user_assigned_client_id),
    AzureCliCredential()
)

Exclure une catégorie de type d’informations d’identification

Pour exclure toutes les informations d'identification de type Developer tool ou Deployed service, définissez la variable d'environnement AZURE_TOKEN_CREDENTIALS sur prod ou dev, respectivement. Lorsqu’une valeur est prod utilisée, la chaîne d’informations d’identification sous-jacente se présente comme suit :

Lorsqu’une valeur est dev utilisée, la chaîne se présente comme suit :

Importante

La AZURE_TOKEN_CREDENTIALS variable d’environnement est prise en charge dans les azure-identity versions de package 1.23.0 et ultérieures.

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 :

credential = ChainedTokenCredential(
    AzureCliCredential(),
    AzureDeveloperCliCredential()
)

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. AzureCliCredential est tentée en premier, suivie de AzureDeveloperCliCredential, 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 ChainedTokenCredential 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 bien démarrer avec la bibliothèque d’identités Azure, mais avec cette commodité vient 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, remplacez DefaultAzureCredential par une implémentation de TokenCredential spécifique, telle que ManagedIdentityCredential.

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. Par conséquent, ManagedIdentityCredential échoue toujours dans l’environnement de développement local, sauf si elle est explicitement désactivée via sa propriété correspondante précédée du préfixe exclude.
• 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. Optionnellement, filtrez les journaux pour ne conserver que ceux émis par la bibliothèque cliente Azure Identity. Par exemple :

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

À des fins d’illustration, supposons que la forme sans paramètre de DefaultAzureCredential soit utilisée pour authentifier une requête à un compte de stockage d’objets blob. 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. Supposons également que le niveau de journalisation soit défini sur logging.DEBUG. Lorsque l’application est exécutée, les entrées pertinentes suivantes apparaissent dans la sortie :

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

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

• EnvironmentCredential, ManagedIdentityCredential et SharedTokenCacheCredential n’ont pas pu acquérir un jeton d’accès Microsoft Entra, dans cet ordre.
• L’appel AzureCliCredential.get_token réussit et la sortie indique également que DefaultAzureCredential a acquis un jeton de AzureCliCredential. Étant donné que AzureCliCredential a réussi, aucune autre information d’identification n’a été essayée.

Remarque

Dans l’exemple précédent, le niveau de journalisation est défini sur logging.DEBUG. Soyez prudent lorsque vous utilisez ce niveau de journalisation, car il peut afficher des informations sensibles. Par exemple, dans ce cas, l’ID client, l’ID locataire et l’ID objet du principal utilisateur du développeur dans Azure. Toutes les informations de trace d’appels ont été supprimées de la sortie pour plus de clarté.