azure-identity-py

Python 版 Azure Identity SDK

用于通过 Microsoft Entra ID（前身为 Azure AD）对 Azure SDK 客户端进行身份验证的库。

安装

pip install azure-identity

环境变量

# Service Principal (for production/CI)
AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<your-client-id>
AZURE_CLIENT_SECRET=<your-client-secret>

# User-assigned Managed Identity (optional)
AZURE_CLIENT_ID=<managed-identity-client-id>

DefaultAzureCredential

适用于开发和灵活的环境。生产环境应选择明确预期使用的凭据（例如工作负载身份或托管身份），而不是意外回退到其他账户。以下凭据链仅供说明，具体顺序取决于版本和配置：

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
)

凭据链顺序

顺序	凭据	环境
1	EnvironmentCredential	CI/CD、容器
2	WorkloadIdentityCredential	Kubernetes
3	ManagedIdentityCredential	Azure VM、App Service、Functions
4	SharedTokenCacheCredential	仅限 Windows
5	VisualStudioCodeCredential	配置了 Azure 扩展的 VS Code
6	AzureCliCredential	az login
7	AzurePowerShellCredential	Connect-AzAccount
8	AzureDeveloperCliCredential	azd auth login

自定义 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
)

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

获取令牌前，请验证租户、客户端/主体、云环境以及所需的受众/范围，不要打印令牌。避免将机密写入提交到代码库的 dotenv 示例，或粘贴到 Shell 历史记录中；在支持的情况下，优先使用托管身份/工作负载身份。在失败路径中关闭凭据/客户端。请查阅当前凭据链指南，了解所选包的相关信息，包括可选的代理/开发者凭据。

特定凭据类型

ManagedIdentityCredential

适用于托管在 Azure 上的资源（VM、App Service、Functions、AKS）：

from azure.identity import ManagedIdentityCredential

# System-assigned managed identity
credential = ManagedIdentityCredential()

# User-assigned managed identity
credential = ManagedIdentityCredential(
    client_id="<user-assigned-mi-client-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"]
)

AzureCliCredential

使用 az login 登录的账户：

from azure.identity import AzureCliCredential

credential = AzureCliCredential()

ChainedTokenCredential

自定义凭据链：

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()
)

凭据类型表

凭据	使用场景	身份验证方法
DefaultAzureCredential	大多数场景	自动检测
ManagedIdentityCredential	托管在 Azure 上的应用	托管身份
ClientSecretCredential	服务主体	客户端机密
ClientCertificateCredential	服务主体	证书
AzureCliCredential	本地开发	Azure CLI
AzureDeveloperCliCredential	本地开发	Azure Developer CLI
InteractiveBrowserCredential	用户登录	浏览器 OAuth
DeviceCodeCredential	无头环境/SSH	设备代码流

直接获取令牌

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")

异步客户端

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

async def main():
    credential = DefaultAzureCredential()
    
    async with BlobServiceClient(
        account_url="https://<account>.blob.core.windows.net",
        credential=credential
    ) as client:
        # ... async operations
        pass
    
    await credential.close()

最佳实践

1. 使用 DefaultAzureCredential 编写可在本地和 Azure 中运行的代码
2. 切勿硬编码凭据——使用环境变量或托管身份
3. 在生产环境的 Azure 部署中优先使用托管身份
4. 需要自定义凭据顺序时使用 ChainedTokenCredential
5. 显式关闭异步凭据，或使用上下文管理器
6. 为用户分配的托管身份设置 AZURE_CLIENT_ID
7. 排除未使用的凭据以加快身份验证

适用场景

当任务适用于执行概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 请勿将输出视为对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。