Bibliothèque cliente Azure Identity pour Python - version 1.14.1
La bibliothèque Azure Identity fournit une prise en charge de l’authentification par jeton Azure Active Directory (Azure AD) dans l’ensemble du Kit de développement logiciel (SDK) Azure. Il fournit un ensemble d’implémentations TokenCredential , qui peuvent être utilisées pour construire des clients du KIT de développement logiciel (SDK) Azure qui prennent en charge l’authentification par jeton Azure AD.
| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | APIDocumentation Azure AD
Prise en main
Installer le package
Installez Azure Identity avec pip :
pip install azure-identity
Prérequis
- Un abonnement Azure
- Python 3.7 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 Azure Identity 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 installé, 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 peut 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 par code d’appareil. Ce flux peut également être sélectionné manuellement en exécutant az login --use-device-code.
S’authentifier via le Azure Developer CLI
Les développeurs qui codent en dehors d’un IDE peuvent également utiliser le Azure Developer CLI pour s’authentifier. Les applications utilisant les DefaultAzureCredential ou AzureDeveloperCliCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.
Pour s’authentifier auprès du Azure Developer CLI, les utilisateurs peuvent exécuter la commande azd auth login. Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut, le Azure Developer CLI lance le navigateur pour authentifier l’utilisateur.
Sur les systèmes sans navigateur web par défaut, la commande azd auth login --use-device-code utilise le flux d’authentification de code d’appareil.
Concepts clés
Titre de compétences
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 du 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 AD. Il propose différentes classes d’informations d’identification capables d’acquérir un jeton d’accès Azure AD. Consultez la section ci-dessous pour obtenir la liste des classes d’informations d’identification de cette bibliothèque.
DefaultAzureCredential
DefaultAzureCredential convient à la plupart des applications qui s’exécutent dans Azure, car il combine les informations d’identification de production courantes avec les informations d’identification de développement. DefaultAzureCredential tente de s’authentifier via les mécanismes suivants, dans cet ordre, en s’arrêtant lorsque l’une d’elles réussit :
Remarque :
DefaultAzureCredentialvise à simplifier la prise en main de la bibliothèque 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.
- Environnement -
DefaultAzureCredentiallit les informations de compte spécifiées via les d’environnement et les utilise pour s’authentifier. - Identité de charge de travail : si l’application est déployée sur Azure Kubernetes Service avec l’identité managée activée,
DefaultAzureCredentials’authentifiera auprès de celle-ci. - Identité managée : si l’application est déployée sur un hôte Azure avec l’identité managée activée,
DefaultAzureCredentials’authentifie auprès de celle-ci. - Azure CLI : si un utilisateur s’est connecté via la commande Azure CLI
az login,DefaultAzureCredentials’authentifie en tant qu’utilisateur. - Azure PowerShell : si un utilisateur s’est connecté via la commande de
Connect-AzAccountAzure PowerShell,DefaultAzureCredentials’authentifie en tant qu’utilisateur. - Azure Developer CLI : si le développeur s’est authentifié via la commande Azure Developer CLI
azd auth login, s’authentifie auprès deDefaultAzureCredentialce compte. - Navigateur interactif : s’il est activé,
DefaultAzureCredentialauthentifie interactivement un utilisateur via le navigateur par défaut. Ce type d’informations d’identification est désactivé par défaut.
Remarque sur VisualStudioCodeCredential
En raison d’un problème connu, VisualStudioCodeCredential a été supprimé de la chaîne de DefaultAzureCredential jetons. Lorsque le problème est résolu dans une version ultérieure, cette modification est rétablie.
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
Authentifier avec DefaultAzureCredential
Pour plus d’informations sur la configuration de votre environnement, DefaultAzureCredential consultez la documentation de référence de la classe.
Cet exemple montre comment authentifier le à 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 dans le DefaultAzureCredential par défaut et peut être activée avec un argument mot clé :
DefaultAzureCredential(exclude_interactive_browser_credential=False)
Lorsque 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 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 des ChainedTokenCredential
DefaultAzureCredential est généralement le moyen le plus rapide de commencer à développer des applications pour Azure. Pour des 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 d’abord de s’authentifier à l’aide d’une identité managée. Les informations d’identification reviennent à 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 comprend 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)
Prise en charge des identités managées
L’authentification d’identité managée est prise en charge via ou DefaultAzureCredentialManagedIdentityCredential 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
- Azure Virtual Machine Scale Sets
Exemples
S’authentifier avec une identité managée affectée par l’utilisateur
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)
S’authentifier avec une identité managée affectée par le système
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
Cloud configuration
Par défaut, les informations d’identification s’authentifient auprès du point de terminaison Azure AD pour le cloud public Azure. Pour accéder aux ressources 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)
Si l’autorité de votre cloud n’est pas répertoriée dans AzureAuthorityHosts, vous pouvez spécifier explicitement son URL :
DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")
Au lieu de spécifier l’argument authority , vous pouvez également définir la AZURE_AUTHORITY_HOST variable d’environnement sur l’URL de l’autorité de votre cloud. Cette approche est utile lors de la configuration de plusieurs informations d’identification pour l’authentification auprès du même cloud :
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
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 |
Fournit une expérience d’authentification simplifiée pour commencer rapidement à développer des applications exécutées dans Azure. |
ChainedTokenCredential |
Permet aux utilisateurs de définir des flux d’authentification personnalisés qui se composent de plusieurs informations d’identification. |
EnvironmentCredential |
Authentifie un principal de service ou un utilisateur via les informations d’identification spécifiées dans les variables d’environnement. |
ManagedIdentityCredential |
Authentifie l’identité managée d’une ressource Azure. |
WorkloadIdentityCredential |
Prend en charge l’identité de charge de travail Azure AD sur Kubernetes. |
Authentifier les principaux de service
| Informations d'identification | Usage | Informations de référence |
|---|---|---|
CertificateCredential |
Authentifie un principal de service à l’aide d’un certificat. | Authentification d’un principal du service |
ClientAssertionCredential |
Authentifie un principal de service à l’aide d’une assertion cliente signée. | |
ClientSecretCredential |
Authentifie un principal de service à l’aide d’un secret. | Authentification d’un principal du service |
Authentification des utilisateurs
| Informations d'identification | Usage | Informations de référence |
|---|---|---|
AuthorizationCodeCredential |
Authentifie un utilisateur avec un code d’autorisation obtenu précédemment. | Code d’authentification OAuth2 |
DeviceCodeCredential |
Authentifie un utilisateur de manière interactive sur les appareils ayant une interface utilisateur limitée. | Authentification de code d’appareil |
InteractiveBrowserCredential |
Authentifie un utilisateur de manière interactive avec le navigateur système par défaut. | Code d’authentification OAuth2 |
OnBehalfOfCredential |
Propage l’identité et les autorisations de l’utilisateur délégué par le biais de la chaîne de demandes. | Authentification de la part de |
UsernamePasswordCredential |
Authentifie un utilisateur avec un nom d’utilisateur et un mot de passe (ne prend pas en charge l’authentification multifacteur). | Authentification par nom d'utilisateur et mot de passe |
S’authentifier via des outils de développement
| Informations d'identification | Usage | Informations de référence |
|---|---|---|
AzureCliCredential |
S’authentifie dans un environnement de développement avec Azure CLI. | Authentification Azure CLI |
AzureDeveloperCliCredential |
S’authentifie dans un environnement de développement avec le Azure Developer CLI. | Référence Azure Developer CLI |
AzurePowerShellCredential |
S’authentifie dans un environnement de développement avec le Azure PowerShell. | 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 une clé secrète
| Nom de la variable | Valeur |
|---|---|
AZURE_CLIENT_ID |
ID d’une application Azure AD |
AZURE_TENANT_ID |
ID du locataire Azure AD de l’application |
AZURE_CLIENT_SECRET |
un des secrets client de l’application |
Principal de service avec un certificat
| Nom de la variable | Valeur |
|---|---|
AZURE_CLIENT_ID |
ID d’une application Azure AD |
AZURE_TENANT_ID |
ID du locataire Azure AD 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 la variable | Valeur |
|---|---|
AZURE_CLIENT_ID |
ID d’une application Azure AD |
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.
Mise en cache de jeton
La mise en cache des jetons est une fonctionnalité fournie par la bibliothèque d’identités Azure qui permet aux applications de :
- Jetons de cache en mémoire (valeur par défaut) ou sur disque (opt-in).
- Améliorez la résilience et les performances.
- Réduisez le nombre de demandes adressées à Azure AD pour obtenir des jetons d’accès.
La bibliothèque d’identités Azure offre une mise en cache de disque persistante et en mémoire. Pour plus d’informations, consultez la documentation relative à la mise en cache des jetons.
Résolution des problèmes
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 déclenche 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 AD spécifiques, consultez la documentation sur les codes d’erreur Azure AD.
Journalisation
Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations d’identification journalisent 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 dans 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, ouvrez 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 n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.
Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d'informations, consultez la FAQ du Code de conduite ou contactez opencode@microsoft.com pour toute question ou commentaire supplémentaire.
