Bibliothèque de client Azure Identity pour Python - version 1.11.0

La bibliothèque Azure Identity fournit l’authentification par jeton Azure Active Directory (AAD) via un ensemble d’implémentations TokenCredential pratiques. Il permet aux clients du SDK Azure de s’authentifier auprès d’AAD, tout en permettant à d’autres applications Python de s’authentifier auprès de comptes professionnels et scolaires AAD, de comptes personnels Microsoft (MSA) et d’autres fournisseurs d’identité comme le service AAD B2C .

| Code sourcePackage (PyPI) | Documentation de référence sur les | API Documentation Azure Active Directory

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Installer le package

Installez Azure Identity avec pip :

pip install azure-identity

Prérequis

• un abonnement Azure
• Python 3.6 ou une version récente de Python 3 (cette bibliothèque ne prend pas en charge les versions en fin de vie)

S’authentifier pendant le développement local

Lors du débogage et de l’exécution de code localement, il est courant pour les développeurs d’utiliser leurs propres comptes pour authentifier les appels aux services Azure. La bibliothèque d’identités Azure prend en charge l’authentification via des outils de développement pour simplifier le développement local.

S’authentifier via Visual Studio Code

Les développeurs qui utilisent Visual Studio Code peuvent utiliser l’extension de compte Azure pour s’authentifier via l’éditeur. Les applications utilisant DefaultAzureCredential ou 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 l’installation terminée, ouvrez la palette de commandes et exécutez la commande Azure : Se connecter .

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

S’authentifier via Azure CLI

DefaultAzureCredential et AzureCliCredential peuvent s’authentifier en tant qu’utilisateur connecté à Azure CLI. Pour vous connecter à Azure CLI, exécutez az login. Sur un système avec un navigateur web par défaut, Azure CLI lance le navigateur pour authentifier un utilisateur.

Lorsqu’aucun navigateur par défaut n’est disponible, az login utilise le flux d’authentification du code de l’appareil. Vous pouvez également la sélectionner manuellement en exécutant az login --use-device-code.

Concepts clés

Informations d'identification

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 une instance d’informations d’identification lorsqu’ils sont construits et utilisent ces informations d’identification pour authentifier les demandes.

La bibliothèque Azure Identity se concentre sur l’authentification OAuth avec Azure Active Directory (AAD). Il offre une variété de classes d’informations d’identification capables d’acquérir un jeton d’accès AAD. Pour obtenir la liste des d’informations d’identification de cette bibliothèque, consultez la section Classes d’informations d’identification ci-dessous.

DefaultAzureCredential

DefaultAzureCredential convient à la plupart des applications qui s’exécutent dans le cloud Azure, car elle combine des informations d’identification de production courantes avec des informations d’identification de développement. DefaultAzureCredential tente de s’authentifier via les mécanismes suivants dans cet ordre, en s’arrêtant quand l’un d’eux réussit :

1. Environnement - DefaultAzureCredential lit les informations de compte spécifiées via les variables d’environnement des et les utilise pour s’authentifier.
2. Identité managée : si l’application est déployée sur un hôte Azure avec l’identité managée activée, DefaultAzureCredential s’authentifie avec elle.
3. Visual Studio Code : si un utilisateur s’est connecté à l’extension de compte Azure Visual Studio Code, DefaultAzureCredential s’authentifie en tant qu’utilisateur.
4. Azure CLI : si un utilisateur s’est connecté via la commande Azure CLI az login , DefaultAzureCredential s’authentifie en tant qu’utilisateur.
5. Azure PowerShell : si un utilisateur s’est connecté via la commande de Connect-AzAccount Azure PowerShell, DefaultAzureCredential s’authentifie en tant qu’utilisateur.
6. Navigateur interactif : s’il est activé, DefaultAzureCredential authentifie de manière interactive un utilisateur via le navigateur par défaut. Elle est désactivée par défaut.

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 davantage de contrôle ou dont le scénario n’est pas pris en charge par les paramètres par défaut doivent utiliser d’autres types d’informations d’identification.

Identité managée

DefaultAzureCredential et ManagedIdentityCredential prennent en charge l’authentification d’identité managée dans tout environnement d’hébergement qui prend en charge les identités managées, par exemple (cette liste n’est pas exhaustive) :

• Machines virtuelles Azure
• Azure App Service
• Azure Kubernetes Service
• Azure Cloud Shell
• Azure Arc
• Azure Service Fabric

Exemples

Les exemples suivants sont fournis ci-dessous :

• S’authentifier avec DefaultAzureCredential
• Définir un flux d’authentification personnalisé avec ChainedTokenCredential
• Informations d’identification asynchrones

S’authentifier avec DefaultAzureCredential

Vous trouverez plus d’informations sur la configuration de votre environnement pour utiliser le DefaultAzureCredential dans la documentation de référence de la classe.

Cet exemple illustre l’authentification du à partir de la bibliothèque azure-storage-blob à l’aide DefaultAzureCredentialBlobServiceClient de .

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Activer l’authentification interactive avec DefaultAzureCredential

L’authentification interactive est désactivée par défaut et DefaultAzureCredential peut être activée avec un argument de mot clé :

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Quand cette option est activée, DefaultAzureCredential elle revient à l’authentification interactive via le navigateur web par défaut du système lorsqu’aucune autre information d’identification n’est disponible.

Spécifier une identité managée affectée par l’utilisateur pour DefaultAzureCredential

De nombreux hôtes Azure autorisent l’attribution d’une identité managée affectée par l’utilisateur. Pour configurer DefaultAzureCredential l’authentification d’une identité affectée par l’utilisateur, utilisez l’argument de managed_identity_client_id mot clé :

DefaultAzureCredential(managed_identity_client_id=client_id)

Vous pouvez également définir la variable AZURE_CLIENT_ID d’environnement sur l’ID client de l’identité.

Définir un flux d’authentification personnalisé avec ChainedTokenCredential

DefaultAzureCredential est généralement le moyen le plus rapide de commencer à développer des applications pour Azure. Pour les scénarios plus avancés, ChainedTokenCredential lie plusieurs instances d’informations d’identification à essayer séquentiellement lors de l’authentification. Il essaiera à son tour chaque informations d’identification chaînées jusqu’à ce que l’un d’eux fournisse un jeton ou ne parvient pas à s’authentifier en raison d’une erreur.

L’exemple suivant illustre la création d’informations d’identification qui tenteront de s’authentifier à l’aide d’une identité managée et revenront à l’authentification via Azure CLI lorsqu’une identité managée n’est pas disponible. Cet exemple utilise le EventHubProducerClient à partir de la bibliothèque de client azure-eventhub .

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

Informations d’identification asynchrones

Cette bibliothèque inclut un ensemble d’API asynchrones. Pour utiliser les informations d’identification asynchrones dans azure.identity.aio, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation azure-core .

Les informations d’identification asynchrones doivent être fermées lorsqu’elles ne sont plus nécessaires. Chaque informations d’identification asynchrones est un gestionnaire de contexte asynchrone et définit une méthode asynchrone close . Par exemple :

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

Cet exemple illustre l’authentification asynchrone SecretClient à partir d’azure-keyvault-secrets avec des informations d’identification asynchrones.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

Cloud configuration

Par défaut, les informations d’identification s’authentifient auprès du point de terminaison Azure Active Directory pour le cloud public Azure. Pour accéder à des ressources dans d’autres clouds, telles que Azure Government ou un cloud privé, configurez les informations d’identification avec l’argument authority . AzureAuthorityHosts définit les autorités pour les clouds connus :

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

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 authority argument, mais utilise par défaut l’autorité correspondant au paramètre « Azure : Cloud » de VS Code.

Classes d’informations d’identification

Authentifier les applications hébergées par Azure

Informations d'identification	Usage
DefaultAzureCredential	Authentification simplifiée pour commencer à développer des applications pour le cloud Azure
ChainedTokenCredential	définir des flux d’authentification personnalisés composant plusieurs informations d’identification
EnvironmentCredential	authentifier un principal de service ou un utilisateur configuré par des variables d’environnement
ManagedIdentityCredential	authentifier l’identité managée d’une ressource Azure

Authentifier les principaux de service

Informations d'identification	Usage
CertificateCredential	authentifier un principal de service à l’aide d’un certificat
ClientAssertionCredential	authentifier un principal de service à l’aide d’une assertion cliente signée
ClientSecretCredential	authentifier un principal de service à l’aide d’un secret

Authentification des utilisateurs

Informations d'identification	Usage
DeviceCodeCredential	authentifier de manière interactive un utilisateur sur un appareil avec une interface utilisateur limitée
InteractiveBrowserCredential	authentifier de manière interactive un utilisateur avec le navigateur web par défaut
OnBehalfOfCredential	propage l’identité et les autorisations d’utilisateur déléguées via la chaîne de requêtes
UsernamePasswordCredential	authentifier un utilisateur avec un nom d’utilisateur et un mot de passe (ne prend pas en charge l’authentification multifacteur)

S’authentifier via des outils de développement

Informations d'identification	Usage
AzureCliCredential	s’authentifier en tant qu’utilisateur connecté à Azure CLI
VisualStudioCodeCredential	s’authentifier en tant qu’utilisateur connecté à l’extension de compte Azure Visual Studio 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 une clé secrète

nom de variable	value
AZURE_CLIENT_ID	id d’une application Azure Active Directory
AZURE_TENANT_ID	id du locataire Azure Active Directory de l’application
AZURE_CLIENT_SECRET	un des secrets client de l’application

Principal de service avec un certificat

nom de variable	value
AZURE_CLIENT_ID	id d’une application Azure Active Directory
AZURE_TENANT_ID	id du locataire Azure Active Directory de l’application
AZURE_CLIENT_CERTIFICATE_PATH	chemin d’accès à un fichier de certificat PEM ou PKCS12 incluant 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 variable	value
AZURE_CLIENT_ID	id d’une application Azure Active Directory
AZURE_USERNAME	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 indiqué ci-dessus. Par exemple, si les valeurs d’un certificat et d’une clé secrète client sont toutes deux présentes, la clé secrète client est utilisée.

Dépannage

Consultez le guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Gestion des erreurs

Les informations d’identification sont levées CredentialUnavailableError lorsqu’elles ne peuvent pas tenter l’authentification, car elles ne disposent pas des données ou de l’état requis. Par exemple, EnvironmentCredential lève cette exception lorsque est incomplète.

Les informations d’identification déclenchent une erreur azure.core.exceptions.ClientAuthenticationError quand l’authentification échoue. ClientAuthenticationError a un message attribut qui décrit la raison de l’échec de l’authentification. Lorsqu’il est déclenché par DefaultAzureCredential ou ChainedTokenCredential, le message collecte les messages d’erreur de chaque informations d’identification dans la chaîne.

Pour plus d’informations sur la gestion des erreurs Azure Active Directory spécifiques, consultez la documentation relative au code d’erreur Azure Active Directory.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations d’identification consignent les informations de base, notamment les sessions HTTP (URL, en-têtes, etc.) au niveau INFO. Ces entrées de journal ne contiennent pas de secrets d’authentification.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les valeurs d’en-tête, n’est pas activée par défaut. Il peut être activé avec l’argument logging_enable , par exemple :

credential = DefaultAzureCredential(logging_enable=True)

ATTENTION : Les journaux de niveau DÉBOGAGE des informations d’identification contiennent des informations sensibles. Ces journaux doivent être protégés pour éviter de compromettre la sécurité du compte.

Étapes suivantes

Prise en charge de la bibliothèque de client

Les bibliothèques clientes et de gestion répertoriées sur la page de publication du KIT de développement logiciel (SDK) Azure qui prennent en charge l’authentification Azure AD acceptent les informations d’identification de cette bibliothèque. Vous pouvez en savoir plus sur l’utilisation de ces bibliothèques dans leur documentation, qui est liée à partir de la page de publication.

Problèmes connus

Cette bibliothèque ne prend pas en charge Azure AD B2C.

Pour d’autres problèmes ouverts, reportez-vous au dépôt GitHub de la bibliothèque.

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.