npx skills add ...
npx skills add microsoft/agent-skills --skill azure-identity-py
npx skills add microsoft/agent-skills --skill azure-identity-py
Azure Identity SDK for Python authentication with Microsoft Entra ID. Use for DefaultAzureCredential, managed identity, service principals, and token caching. Triggers: "azure-identity", "DefaultAzureCredential", "authentication", "managed identity", "service principal", "credential".
The same skill content is published under more than one repo. The install counts are split across them; any of these commands works.
Authentication library for Azure SDK clients using Microsoft Entra ID.
Use this skill when:
DefaultAzureCredential for local dev + Azure deploymentManagedIdentityCredential for Azure-hosted workloadsget_token()For VS Code or broker-based desktop auth:
azure-identity supports Python 3.9+.
🔑 Two rules apply to every code sample below:
- Prefer
DefaultAzureCredential. It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
- Local dev:
DefaultAzureCredentialworks as-is.- Production: set
AZURE_TOKEN_CREDENTIALS=prod(orAZURE_TOKEN_CREDENTIALS=<specific_credential>) to constrain the credential chain to production-safe credentials.- Wrap credentials and clients in context managers when they own token caches / transports:
- Sync:
with DefaultAzureCredential() as credential:- Async:
async with DefaultAzureCredential() as credential:(fromazure.identity.aio)Snippets may abbreviate this setup, but production code should always follow both rules.
The recommended credential for most scenarios. Tries multiple authentication methods in order:
See DefaultAzureCredential overview for the current credential chain order and defaults.
| 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 |
Helper that wraps a credential into a callable returning a bearer token string. Essential for OpenAI SDK and other non-Azure-SDK clients:
| Credential | Use Case |
|---|---|
DefaultAzureCredential | Most scenarios — auto-detects environment |
ChainedTokenCredential | Custom credential chain with explicit ordering |
| 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 |
| 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) |
| Credential | Use Case |
|---|---|
InteractiveBrowserCredential | Interactive browser OAuth sign-in |
DeviceCodeCredential | Headless/SSH device code flow |
AuthorizationCodeCredential | Previously obtained authorization code |
| Credential | Use Case |
|---|---|
AzureCliCredential | az login |
AzureDeveloperCliCredential | azd auth login |
AzurePowerShellCredential | Connect-AzAccount |
VisualStudioCodeCredential | VS Code Azure Resources extension |
For Azure-hosted resources (VMs, App Service, Functions, AKS):
Note: The class is
CertificateCredential, NOTClientCertificateCredential.
Custom credential chain:
For Azure Kubernetes Service with workload identity:
For headless devices (IoT, SSH, CLI tools):
For interactive OAuth browser sign-in:
For middle-tier services propagating user identity:
For Azure DevOps pipelines with workload identity federation:
Async credentials are in azure.identity.aio. Always close them or use async with:
The async
get_bearer_token_provideris atazure.identity.aio.get_bearer_token_provider.
Use AzureAuthorityHosts or the AZURE_AUTHORITY_HOST env var:
| Constant | Authority |
|---|---|
AzureAuthorityHosts.AZURE_PUBLIC_CLOUD | login.microsoftonline.com (default) |
AzureAuthorityHosts.AZURE_GOVERNMENT | login.microsoftonline.us |
AzureAuthorityHosts.AZURE_CHINA | login.chinacloudapi.cn |
Opt-in disk-based caching with TokenCachePersistenceOptions:
Storage: Windows (DPAPI), macOS (Keychain), Linux (Keyring).
Allow token acquisition for additional tenants beyond the configured one:
Enable authentication logging for debugging:
| 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 |
azure.xxx sync clients with azure.xxx.aio async clients in the same call path. Choose one mode per module.with DefaultAzureCredential() as credential:) when they own token caches / HTTP transports you want cleaned up; for async, use async with on credentials from azure.identity.aio.DefaultAzureCredential for code that runs locally. Use a specific token credential for code that runs in Azure.get_bearer_token_provider for non-Azure-SDK clients (OpenAI, REST APIs)ChainedTokenCredential when you need a custom credential orderAZURE_CLIENT_ID for user-assigned managed identities (object ID and resource ID are also valid identifiers)DefaultAzureCredential authenticationCertificateCredential (not ClientCertificateCredential — that name doesn't exist)cache_persistence_options for long-running services to reduce token requests| 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 |
| File | Contents |
|---|---|
| references/capabilities.md | Additional non-hero capabilities, operation-group coverage, and production checklists. |
| references/non-hero-scenarios.md | Dedicated non-hero examples for secondary/advanced scenarios. |
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
# Works in local dev AND production without code changes
credential = DefaultAzureCredential()
with BlobServiceClient(
account_url="https://<account>.blob.core.windows.net",
credential=credential
) as client:
containers = list(client.list_containers())# 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)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
with AzureOpenAI(
azure_endpoint="https://<resource>.openai.azure.com/",
azure_ad_token_provider=token_provider,
api_version="2024-10-21",
) as client:
# response = client.chat.completions.create(...)
...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>")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"],
)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
)from azure.identity import AzureCliCredential
credential = AzureCliCredential()
# With tenant restriction
credential = AzureCliCredential(tenant_id="<tenant-id>")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(),
)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",
)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,
)from azure.identity import InteractiveBrowserCredential
credential = InteractiveBrowserCredential()
# With specific tenant and client
credential = InteractiveBrowserCredential(
tenant_id="<tenant-id>",
client_id="<client-id>",
)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>",
)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"],
)from azure.identity import DefaultAzureCredential
with DefaultAzureCredential() as credential:
# 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")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
passfrom azure.identity import DefaultAzureCredential, AzureAuthorityHosts
# Azure Government
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
# Azure China
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)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)
)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
)from azure.identity import DefaultAzureCredential, CredentialUnavailableError
from azure.core.exceptions import ClientAuthenticationError
with DefaultAzureCredential() as credential:
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
passimport 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