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 : DefaultAzureCredential vise à 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.

1. Environnement - DefaultAzureCredential lit les informations de compte spécifiées via les d’environnement et les utilise pour s’authentifier.
2. Identité de charge de travail : si l’application est déployée sur Azure Kubernetes Service avec l’identité managée activée, DefaultAzureCredential s’authentifiera auprès de celle-ci.
3. 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 auprès de celle-ci.
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. Azure Developer CLI : si le développeur s’est authentifié via la commande Azure Developer CLIazd auth login, s’authentifie auprès de DefaultAzureCredential ce compte.
7. Navigateur interactif : s’il est activé, DefaultAzureCredential authentifie 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

Authentifier les principaux de service

Authentification des utilisateurs

S’authentifier via des outils de développement

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

Principal de service avec un certificat

Nom d’utilisateur et mot de passe

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.