Skills
skills/microsoft/skills/azure-identity-py

azure-identity-py

Installation
SKILL.md

Azure Identity library for Python

Authentication library for Azure SDK clients using Microsoft Entra ID.

Use this skill when:

  • An app needs to authenticate to Azure services from Python
  • You need DefaultAzureCredential for local dev + Azure deployment
  • You need ManagedIdentityCredential for Azure-hosted workloads
  • You need service principal auth with secret or certificate
  • You need direct token acquisition with get_token()
  • You need to troubleshoot credential chain failures

Installation

pip install azure-identity

For VS Code or broker-based desktop auth:

pip install azure-identity-broker

Python Version

azure-identity supports Python 3.9+.

Environment Variables

# Service principal with client secret
AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<your-client-id>
AZURE_CLIENT_SECRET=<your-client-secret>

# Service principal with certificate
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>

# Authority (sovereign clouds)
AZURE_AUTHORITY_HOST=login.microsoftonline.com  # Default; or login.chinacloudapi.cn, login.microsoftonline.us

# User-assigned managed identity
AZURE_CLIENT_ID=<managed-identity-client-id>

# Credential selection (new)
AZURE_TOKEN_CREDENTIALS=dev|prod|<credential-name>  # Optional, restricts DAC chain

DefaultAzureCredential

The recommended credential for most scenarios. Tries multiple authentication methods in order:

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

# Works in local dev AND production without code changes
credential = DefaultAzureCredential()

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

Credential Chain Order

See DefaultAzureCredential overview for the current credential chain order and defaults.

Customizing DefaultAzureCredential

# Exclude credentials you don't need
credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_shared_token_cache_credential=True,
    managed_identity_client_id="<user-assigned-mi-client-id>"  # For user-assigned MI (also accepts object ID or resource ID)
)

# Enable interactive browser (disabled by default)
credential = DefaultAzureCredential(
    exclude_interactive_browser_credential=False
)

# Set subprocess timeout for CLI-based credentials (default: 10s)
credential = DefaultAzureCredential(process_timeout=30)

# Require AZURE_TOKEN_CREDENTIALS env var to be set
credential = DefaultAzureCredential(require_envvar=True)

Exclude Parameters

Parameter Default Effect
exclude_environment_credential False Skip env-var-based auth
exclude_workload_identity_credential False Skip Kubernetes workload identity
exclude_managed_identity_credential False Skip managed identity
exclude_shared_token_cache_credential False Skip shared token cache
exclude_visual_studio_code_credential False Skip VS Code credential
exclude_cli_credential False Skip Azure CLI
exclude_powershell_credential False Skip Azure PowerShell
exclude_developer_cli_credential False Skip Azure Developer CLI
exclude_interactive_browser_credential True Skip interactive browser
exclude_broker_credential False Skip WAM broker

get_bearer_token_provider

Helper that wraps a credential into a callable returning a bearer token string. Essential for OpenAI SDK and other non-Azure-SDK clients:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

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

# Use with OpenAI SDK
from openai import AzureOpenAI

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

Credential Types

Credential Chains

Credential Use Case
DefaultAzureCredential Most scenarios — auto-detects environment
ChainedTokenCredential Custom credential chain with explicit ordering

Azure-Hosted Applications

Credential Use Case
EnvironmentCredential Auth via AZURE_CLIENT_SECRET / AZURE_CLIENT_CERTIFICATE_PATH env vars
ManagedIdentityCredential Azure VMs, App Service, Functions, AKS, Arc, Service Fabric
WorkloadIdentityCredential Kubernetes with Microsoft Entra Workload ID

Service Principals

Credential Use Case
ClientSecretCredential Service principal with client secret
CertificateCredential Service principal with PEM/PKCS12 certificate
ClientAssertionCredential Service principal with signed JWT assertion
AzurePipelinesCredential Azure Pipelines with workload identity federation
OnBehalfOfCredential Middle-tier on-behalf-of flow (delegated user identity)

User Authentication

Credential Use Case
InteractiveBrowserCredential Interactive browser OAuth sign-in
DeviceCodeCredential Headless/SSH device code flow
AuthorizationCodeCredential Previously obtained authorization code

Developer Tools

Credential Use Case
AzureCliCredential az login
AzureDeveloperCliCredential azd auth login
AzurePowerShellCredential Connect-AzAccount
VisualStudioCodeCredential VS Code Azure Resources extension

Specific Credential Examples

ManagedIdentityCredential

For Azure-hosted resources (VMs, App Service, Functions, AKS):

from azure.identity import ManagedIdentityCredential

# System-assigned managed identity
credential = ManagedIdentityCredential()

# User-assigned managed identity (client_id, object_id, or resource_id)
credential = ManagedIdentityCredential(
    client_id="<user-assigned-mi-client-id>"
)
# Also valid:
# 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

Note: The class is CertificateCredential, NOT ClientCertificateCredential.

from azure.identity import CertificateCredential

# From file path
credential = CertificateCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    certificate_path="/path/to/cert.pem",
)

# From bytes with password
credential = CertificateCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
    certificate_data=cert_bytes,
    password="<cert-password>",
    send_certificate_chain=True,  # Required for SNI auth
)

AzureCliCredential

from azure.identity import AzureCliCredential

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

ChainedTokenCredential

Custom credential chain:

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

# Try managed identity first, fall back to CLI
credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id="<user-assigned-mi-client-id>"),
    AzureCliCredential(),
)

WorkloadIdentityCredential

For Azure Kubernetes Service with workload identity:

from azure.identity import WorkloadIdentityCredential

# Reads from AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE
credential = WorkloadIdentityCredential()

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

DeviceCodeCredential

For headless devices (IoT, SSH, CLI tools):

from azure.identity import DeviceCodeCredential

credential = DeviceCodeCredential()
# Prints device code prompt to stdout by default

# With custom prompt callback
def prompt_callback(verification_uri, user_code, expires_on):
    print(f"Go to {verification_uri} and enter code {user_code}")

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

InteractiveBrowserCredential

For interactive OAuth browser sign-in:

from azure.identity import InteractiveBrowserCredential

credential = InteractiveBrowserCredential()

# With specific tenant and client
credential = InteractiveBrowserCredential(
    tenant_id="<tenant-id>",
    client_id="<client-id>",
)

OnBehalfOfCredential

For middle-tier services propagating user identity:

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

For Azure DevOps pipelines with 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"],
)

Getting Tokens Directly

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

# Get token for a specific scope
token = credential.get_token("https://management.azure.com/.default")
print(f"Token expires: {token.expires_on}")

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

Async Credentials

Async credentials are in azure.identity.aio. Always close them or use async with:

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

async def main():
    # Preferred: use async context manager for both credential and client
    async with DefaultAzureCredential() as credential:
        async with BlobServiceClient(
            account_url="https://<account>.blob.core.windows.net",
            credential=credential,
        ) as client:
            # ... async operations
            pass

The async get_bearer_token_provider is at azure.identity.aio.get_bearer_token_provider.

Sovereign Clouds

Use AzureAuthorityHosts or the AZURE_AUTHORITY_HOST env var:

from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

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

# Azure China
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)
Constant Authority
AzureAuthorityHosts.AZURE_PUBLIC_CLOUD login.microsoftonline.com (default)
AzureAuthorityHosts.AZURE_GOVERNMENT login.microsoftonline.us
AzureAuthorityHosts.AZURE_CHINA login.chinacloudapi.cn

Persistent Token Caching

Opt-in disk-based caching with TokenCachePersistenceOptions:

from azure.identity import DefaultAzureCredential, TokenCachePersistenceOptions

credential = DefaultAzureCredential(
    cache_persistence_options=TokenCachePersistenceOptions()
)

# Allow unencrypted fallback (NOT recommended for production)
credential = DefaultAzureCredential(
    cache_persistence_options=TokenCachePersistenceOptions(allow_unencrypted_storage=True)
)

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

Multi-Tenant Support

Allow token acquisition for additional tenants beyond the configured one:

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id="<home-tenant>",
    client_id="<client-id>",
    client_secret="<secret>",
    additionally_allowed_tenants=["<other-tenant>", "*"],  # "*" allows any tenant
)

Error Handling

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:
    # No credential in the chain could attempt authentication
    pass
except ClientAuthenticationError as e:
    # Authentication was attempted but failed
    # e.message contains details from each credential in the chain
    pass

Logging

Enable authentication logging for debugging:

import logging

# Enable verbose Azure Identity logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Or via environment variable
AZURE_LOG_LEVEL=debug

Credential Selection Matrix

Environment Recommended Credential
Local Development DefaultAzureCredential (uses Azure CLI)
Azure App Service DefaultAzureCredential (uses Managed Identity)
Azure Functions DefaultAzureCredential (uses Managed Identity)
Azure Kubernetes Service WorkloadIdentityCredential
Azure VMs DefaultAzureCredential (uses Managed Identity)
CI/CD Pipeline EnvironmentCredential or AzurePipelinesCredential
Desktop App InteractiveBrowserCredential
CLI / Headless Tool DeviceCodeCredential
Middle-tier Service OnBehalfOfCredential

Best Practices

  1. Use DefaultAzureCredential for code that runs locally and in Azure
  2. Never hardcode credentials — use environment variables or managed identity
  3. Prefer managed identity in production Azure deployments
  4. Use get_bearer_token_provider for non-Azure-SDK clients (OpenAI, REST APIs)
  5. Use ChainedTokenCredential when you need a custom credential order
  6. Close async credentials — use async with credential: context manager
  7. Set AZURE_CLIENT_ID for user-assigned managed identities (object ID and resource ID are also valid identifiers)
  8. Exclude unused credentials to speed up DefaultAzureCredential authentication
  9. Use CertificateCredential (not ClientCertificateCredential — that name doesn't exist)
  10. Enable cache_persistence_options for long-running services to reduce token requests
  11. Reuse credential instances — same credential can be shared across multiple clients

Reference Links

Resource URL
PyPI Package https://pypi.org/project/azure-identity/
API Reference https://learn.microsoft.com/python/api/azure-identity
GitHub Source https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
Credential Chains https://aka.ms/azsdk/python/identity/credential-chains
Weekly Installs
2
Repository
microsoft/skills
GitHub Stars
2.2K
First Seen
3 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass