Bibliothèque Azure Identity pour Python

Bibliothèque d'authentification pour les clients du SDK Azure utilisant Microsoft Entra ID.

Utilise cette compétence quand :

• Une application doit s'authentifier auprès des services Azure depuis Python
• Tu as besoin de DefaultAzureCredential pour le dev local + déploiement Azure
• Tu as besoin de ManagedIdentityCredential pour les charges de travail hébergées sur Azure
• Tu as besoin d'une authentification de principal de service avec secret ou certificat
• Tu as besoin d'une acquisition directe de token avec get_token()
• Tu dois dépanner les défaillances de la chaîne d'authentification

Installation

pip install azure-identity

Pour VS Code ou l'authentification de bureau basée sur broker :

pip install azure-identity-broker

Version Python

azure-identity supporte Python 3.9+.

Variables d'environnement

# Principal de service avec secret client
AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<your-client-id>
AZURE_CLIENT_SECRET=<your-client-secret>

# Principal de service avec certificat
AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<your-client-id>
AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pem
AZURE_CLIENT_CERTIFICATE_PASSWORD=<optional-password>

# Autorité (nuages souverains)
AZURE_AUTHORITY_HOST=login.microsoftonline.com  # Par défaut ; ou login.chinacloudapi.cn, login.microsoftonline.us

# Identité managée affectée par l'utilisateur
AZURE_CLIENT_ID=<managed-identity-client-id>

# Sélection des authentifiants (nouveau)
AZURE_TOKEN_CREDENTIALS=dev|prod|<credential-name>  # Optionnel, restreint la chaîne DAC

DefaultAzureCredential

L'authentifiant recommandé pour la plupart des scénarios. Essaie plusieurs méthodes d'authentification en ordre :

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

# Fonctionne en dev local ET en production sans changement de code
credential = DefaultAzureCredential()

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

Ordre de la chaîne d'authentification

Consulte Aperçu de DefaultAzureCredential pour l'ordre actuel de la chaîne d'authentification et les paramètres par défaut.

Personnaliser DefaultAzureCredential

# Exclure les authentifiants dont tu n'as pas besoin
credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_shared_token_cache_credential=True,
    managed_identity_client_id="<user-assigned-mi-client-id>"  # Pour identité managée affectée par l'utilisateur (accepte aussi object ID ou resource ID)
)

# Activer le navigateur interactif (désactivé par défaut)
credential = DefaultAzureCredential(
    exclude_interactive_browser_credential=False
)

# Définir le timeout de sous-processus pour les authentifiants basés sur CLI (par défaut : 10s)
credential = DefaultAzureCredential(process_timeout=30)

# Exiger que la variable d'environnement AZURE_TOKEN_CREDENTIALS soit définie
credential = DefaultAzureCredential(require_envvar=True)

Paramètres d'exclusion

get_bearer_token_provider

Fonction utilitaire qui encapsule un authentifiant dans un callable retournant une chaîne de token bearer. Essentiel pour le SDK OpenAI et autres clients non-Azure-SDK :

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)

# Utiliser avec le SDK OpenAI
from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://<resource>.openai.azure.com/",
    azure_ad_token_provider=token_provider,
    api_version="2024-10-21",
)

Types d'authentifiants

Chaînes d'authentification

Applications hébergées sur Azure

Principaux de service

Authentification utilisateur

Outils de développeur

Exemples spécifiques d'authentifiants

ManagedIdentityCredential

Pour les ressources hébergées sur Azure (VMs, App Service, Functions, AKS) :

from azure.identity import ManagedIdentityCredential

# Identité managée affectée par le système
credential = ManagedIdentityCredential()

# Identité managée affectée par l'utilisateur (client_id, object_id, ou resource_id)
credential = ManagedIdentityCredential(
    client_id="<user-assigned-mi-client-id>"
)
# Également valide :
# credential = ManagedIdentityCredential(object_id="<object-id>")
# credential = ManagedIdentityCredential(resource_id="<resource-id>")

ClientSecretCredential

import os
from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id=os.environ["AZURE_TENANT_ID"],
    client_id=os.environ["AZURE_CLIENT_ID"],
    client_secret=os.environ["AZURE_CLIENT_SECRET"],
)

CertificateCredential

Remarque : La classe est CertificateCredential, PAS ClientCertificateCredential.

from azure.identity import CertificateCredential

# À partir d'un chemin de fichier
credential = CertificateCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    certificate_path="/path/to/cert.pem",
)

# À partir de bytes avec mot de passe
credential = CertificateCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    certificate_data=cert_bytes,
    password="<cert-password>",
    send_certificate_chain=True,  # Requis pour l'auth SNI
)

AzureCliCredential

from azure.identity import AzureCliCredential

credential = AzureCliCredential()
# Avec restriction de tenant
credential = AzureCliCredential(tenant_id="<tenant-id>")

ChainedTokenCredential

Chaîne d'authentification personnalisée :

from azure.identity import (
    ChainedTokenCredential,
    ManagedIdentityCredential,
    AzureCliCredential,
)

# Essayer d'abord l'identité managée, puis revenir à CLI
credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id="<user-assigned-mi-client-id>"),
    AzureCliCredential(),
)

WorkloadIdentityCredential

Pour Azure Kubernetes Service avec workload identity :

from azure.identity import WorkloadIdentityCredential

# Lit depuis AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE
credential = WorkloadIdentityCredential()

# Ou configuration explicite
credential = WorkloadIdentityCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    token_file_path="/var/run/secrets/azure/tokens/azure-identity-token",
)

DeviceCodeCredential

Pour les appareils sans interface graphique (IoT, SSH, outils CLI) :

from azure.identity import DeviceCodeCredential

credential = DeviceCodeCredential()
# Affiche le code de l'appareil sur stdout par défaut

# Avec callback de prompt personnalisé
def prompt_callback(verification_uri, user_code, expires_on):
    print(f"Va à {verification_uri} et entre le code {user_code}")

credential = DeviceCodeCredential(
    client_id="<client-id>",
    prompt_callback=prompt_callback,
)

InteractiveBrowserCredential

Pour la connexion OAuth interactive via navigateur :

from azure.identity import InteractiveBrowserCredential

credential = InteractiveBrowserCredential()

# Avec tenant et client spécifiques
credential = InteractiveBrowserCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
)

OnBehalfOfCredential

Pour les services de niveau intermédiaire propageant l'identité utilisateur :

from azure.identity import OnBehalfOfCredential

credential = OnBehalfOfCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    client_secret="<client-secret>",
    user_assertion="<access-token-from-client>",
)

AzurePipelinesCredential

Pour les pipelines Azure DevOps avec workload identity federation :

import os
from azure.identity import AzurePipelinesCredential

credential = AzurePipelinesCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    service_connection_id="<service-connection-id>",
    system_access_token=os.environ["SYSTEM_ACCESSTOKEN"],
)

Obtenir les tokens directement

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

# Obtenir un token pour un scope spécifique
token = credential.get_token("https://management.azure.com/.default")
print(f"Token expires: {token.expires_on}")

# Pour Azure Database for PostgreSQL
token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default")

Authentifiants asynchrones

Les authentifiants asynchrones sont dans azure.identity.aio. Ferme-les toujours ou utilise async with :

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

async def main():
    # Préféré : utiliser le gestionnaire de contexte async pour l'authentifiant et le client
    async with DefaultAzureCredential() as credential:
        async with BlobServiceClient(
            account_url="https://<account>.blob.core.windows.net",
            credential=credential,
        ) as client:
            # ... opérations asynchrones
            pass

La fonction asynchrone get_bearer_token_provider se trouve dans azure.identity.aio.get_bearer_token_provider.

Nuages souverains

Utilise AzureAuthorityHosts ou la variable d'environnement AZURE_AUTHORITY_HOST :

from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Government
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

# Azure China
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)

Cache de tokens persistant

Mise en cache sur disque optionnelle avec TokenCachePersistenceOptions :

from azure.identity import DefaultAzureCredential, TokenCachePersistenceOptions

credential = DefaultAzureCredential(
    cache_persistence_options=TokenCachePersistenceOptions()
)

# Autoriser le fallback non chiffré (NON recommandé en production)
credential = DefaultAzureCredential(
    cache_persistence_options=TokenCachePersistenceOptions(allow_unencrypted_storage=True)
)

Stockage : Windows (DPAPI), macOS (Keychain), Linux (Keyring).

Support multi-tenant

Autoriser l'acquisition de tokens pour des tenants supplémentaires au-delà du tenant configuré :

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id="<home-tenant>",
    client_id="<client-id>",
    client_secret="<secret>",
    additionally_allowed_tenants=["<other-tenant>", "*"],  # "*" autorise n'importe quel tenant
)

Gestion des erreurs

from azure.identity import DefaultAzureCredential, CredentialUnavailableError
from azure.core.exceptions import ClientAuthenticationError

credential = DefaultAzureCredential()
try:
    token = credential.get_token("https://management.azure.com/.default")
except CredentialUnavailableError:
    # Aucun authentifiant dans la chaîne n'a pu tenter l'authentification
    pass
except ClientAuthenticationError as e:
    # L'authentification a été tentée mais a échoué
    # e.message contient les détails de chaque authentifiant dans la chaîne
    pass

Journalisation

Activer la journalisation d'authentification pour le dépannage :

import logging

# Activer la journalisation verbale d'Azure Identity
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Ou via variable d'environnement
AZURE_LOG_LEVEL=debug

Matrice de sélection d'authentifiants

Bonnes pratiques

1. Utilise DefaultAzureCredential pour le code qui s'exécute localement et sur Azure
2. Ne code jamais les identifiants en dur — utilise des variables d'environnement ou l'identité managée
3. Préfère l'identité managée dans les déploiements Azure en production
4. Utilise get_bearer_token_provider pour les clients non-Azure-SDK (OpenAI, API REST)
5. Utilise ChainedTokenCredential quand tu as besoin d'un ordre personnalisé d'authentifiants
6. Ferme les authentifiants asynchrones — utilise le gestionnaire de contexte async with credential:
7. Définis AZURE_CLIENT_ID pour les identités managées affectées par l'utilisateur (object ID et resource ID sont aussi des identifiants valides)
8. Exclue les authentifiants inutilisés pour accélérer l'authentification avec DefaultAzureCredential
9. Utilise CertificateCredential (pas ClientCertificateCredential — ce nom n'existe pas)
10. Active cache_persistence_options pour les services long-running pour réduire les demandes de token
11. Réutilise les instances d'authentifiants — le même authentifiant peut être partagé entre plusieurs clients

Liens de référence