你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 Python 的 Azure 标识客户端库 - 版本 1.14.1
Azure 标识库跨 Azure SDK 提供 Azure Active Directory (Azure AD) 令牌身份验证支持。 它提供一组 TokenCredential 实现，可用于构造支持 Azure AD 令牌身份验证的 Azure SDK 客户端。
源代码 | 包 (PyPI) | 包 (Conda) | API 参考文档 | Azure AD 文档
入门
安装包
使用 pip 安装 Azure 标识：
pip install azure-identity
先决条件
- Azure 订阅
- Python 3.7 或 Python 3 的最新版本 (此库不支持生命周期结束版本)
在本地开发期间进行身份验证
在本地调试和执行代码时，开发人员通常使用自己的帐户对 Azure 服务的调用进行身份验证。 Azure 标识库支持通过开发人员工具进行身份验证，以简化本地开发。
通过 Visual Studio Code 进行身份验证
使用 Visual Studio Code 的开发人员可以使用 Azure 帐户扩展通过编辑器进行身份验证。 然后，使用 DefaultAzureCredential 或 VisualStudioCodeCredential 的应用可以在本地运行时使用此帐户在其应用中对调用进行身份验证。
若要在 Visual Studio Code 中进行身份验证，请确保已安装 Azure 帐户扩展。 安装后，打开 命令面板 并运行 Azure：登录 命令。
这是一个已知问题，VisualStudioCodeCredential不适用于低于 0.9.11 的 Azure 帐户扩展版本。 正在对此问题进行长期修复。 同时，请考虑 通过 Azure CLI 进行身份验证。
通过 Azure CLI 进行身份验证
DefaultAzureCredential 和 AzureCliCredential 可以作为登录到 Azure CLI 的用户进行身份验证。 若要登录到 Azure CLI，请运行 az login。 在具有默认 Web 浏览器的系统上，Azure CLI 将启动浏览器来对用户进行身份验证。
如果没有可用的默认浏览器， az login 将使用设备代码身份验证流。 也可以通过运行 az login --use-device-code手动选择此流。
通过Azure Developer CLI进行身份验证
在 IDE 外部编码的开发人员也可以使用Azure Developer CLI进行身份验证。 然后，使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。
若要使用 Azure Developer CLI进行身份验证，用户可以运行命令 azd auth login。 对于在具有默认 Web 浏览器的系统上运行的用户，Azure Developer CLI将启动浏览器来对用户进行身份验证。
对于没有默认 Web 浏览器的系统，azd auth login --use-device-code 命令将使用设备代码身份验证流。
关键概念
凭据
凭据是一种类，包含或可以获取服务客户端对请求进行身份验证所需的数据。 Azure SDK 中的服务客户端在构造凭据实例时接受凭据实例，并使用该凭据对请求进行身份验证。
Azure 标识库侧重于使用 Azure AD 进行 OAuth 身份验证。 它提供各种能够获取 Azure AD 访问令牌的凭据类。 有关此库 类 的列表，请参阅下面的凭据类凭据类部分。
DefaultAzureCredential
DefaultAzureCredential 适用于将在 Azure 中运行的大多数应用程序，因为它将常见的生产凭据与开发凭据相结合。 DefaultAzureCredential 尝试通过以下机制进行身份验证，按此顺序，在成功时停止：
注意：
DefaultAzureCredential旨在通过处理具有合理默认行为的常见方案来简化库入门。 对于想要拥有更多控制或其方案缺少默认设置的开发人员，应使用其他凭据类型。
- 环境 -
DefaultAzureCredential将读取通过环境变量指定的帐户信息，并使用它进行身份验证。 - 工作负载标识 - 如果将应用程序部署到启用了托管标识的 Azure Kubernetes 服务，
DefaultAzureCredential将使用它进行身份验证。 - 托管标识 - 如果应用程序部署到启用了托管标识的 Azure 主机，
DefaultAzureCredential将使用它进行身份验证。 - Azure CLI - 如果用户已通过 Azure CLI
az login命令登录，DefaultAzureCredential将作为该用户进行身份验证。 - Azure PowerShell - 如果用户已通过 Azure PowerShell 的
Connect-AzAccount命令登录，DefaultAzureCredential将作为该用户进行身份验证。 - Azure Developer CLI - 如果开发人员已通过 Azure Developer CLI
azd auth login命令进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。 - 交互式浏览器 - 如果启用，
DefaultAzureCredential将通过默认浏览器以交互方式对用户进行身份验证。 默认情况下，此凭据类型处于禁用状态。
关于 的注意事项 VisualStudioCodeCredential
由于 已知问题， VisualStudioCodeCredential 已从令牌链中删除 DefaultAzureCredential 。 在将来的版本中解决问题后，将还原此更改。
示例
下面提供了以下示例：
使用 DefaultAzureCredential 进行身份验证
有关将环境配置为使用 DefaultAzureCredential 的更多详细信息，请参阅类的 参考文档。
此示例演示如何使用 DefaultAzureCredential从 azure-storage-blob 库对 进行身份验证BlobServiceClient。
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
default_credential = DefaultAzureCredential()
client = BlobServiceClient(account_url, credential=default_credential)
使用 启用交互式身份验证 DefaultAzureCredential
默认情况下，交互式身份验证在 中DefaultAzureCredential处于禁用状态，并且可以使用 关键字 (keyword) 参数启用：
DefaultAzureCredential(exclude_interactive_browser_credential=False)
启用后， DefaultAzureCredential 当没有其他凭据可用时，回退到通过系统的默认 Web 浏览器以交互方式进行身份验证。
为 指定用户分配的托管标识 DefaultAzureCredential
许多 Azure 主机允许分配用户分配的托管标识。 若要将 DefaultAzureCredential 配置为对用户分配的标识进行身份验证，请使用 managed_identity_client_id 关键字 (keyword) 参数：
DefaultAzureCredential(managed_identity_client_id=client_id)
或者，将环境变量 AZURE_CLIENT_ID 设置为标识的客户端 ID。
使用 ChainedTokenCredential 定义自定义身份验证流
DefaultAzureCredential 通常是开始为 Azure 开发应用程序的最快方法。 对于更高级的方案， ChainedTokenCredential 链接多个凭据实例，以便在进行身份验证时按顺序尝试。 它将依次尝试每个链接的凭据，直到提供令牌或由于错误而无法进行身份验证。
以下示例演示如何创建一个凭据，该凭据将首先尝试使用托管标识进行身份验证。 当托管标识不可用时，凭据将回退到通过 Azure CLI 进行身份验证。 此示例使用 EventHubProducerClientazure-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)
异步凭据
此库包含一组异步 API。 若要在 azure.identity.aio 中使用异步凭据，必须先安装异步传输，例如 aiohttp。 有关详细信息，请参阅 azure-core 文档。
不再需要异步凭据时，应将其关闭。 每个异步凭据都是一个异步上下文管理器，并定义一个异步 close 方法。 例如：
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:
...
此示例演示如何使用异步 SecretClient 凭据从 azure-keyvault-secrets 对异步进行身份验证。
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)
托管标识支持
对于以下 Azure 服务，通过 或 ManagedIdentityCredential 直接支持DefaultAzureCredential托管标识身份验证：
- Azure 应用服务和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes 服务
- Azure Service Fabric
- Azure 虚拟机
- Azure 虚拟机规模集
示例
使用用户分配的托管标识进行身份验证
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)
使用系统分配的托管标识进行身份验证
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
云配置
凭据默认为向 Azure 公有云的 Azure AD 终结点进行身份验证。 若要访问其他云中的资源（例如Azure 政府或私有云），请使用 参数配置凭据authority。 AzureAuthorityHosts 定义已知云的颁发机构：
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
如果 云的颁发机构未在 中 AzureAuthorityHosts列出，则可以显式指定其 URL：
DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")
作为指定 参数的 authority 替代方法，还可以将 AZURE_AUTHORITY_HOST 环境变量设置为云颁发机构的 URL。 在配置多个凭据以向同一个云进行身份验证时，此方法非常有用：
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
并非所有凭据都需要此配置。 通过开发工具（如 AzureCliCredential）进行身份验证的凭据使用该工具的配置。 同样， VisualStudioCodeCredential 接受 参数， authority 但默认为与 VS Code 的“Azure： 云”设置匹配的颁发机构。
凭据类
对 Azure 托管的应用程序进行身份验证
| 凭据 | 使用情况 |
|---|---|
DefaultAzureCredential |
提供简化的身份验证体验，以快速开始开发在 Azure 中运行的应用程序。 |
ChainedTokenCredential |
允许用户定义组成多个凭据的自定义身份验证流。 |
EnvironmentCredential |
通过环境变量中指定的凭据信息对服务主体或用户进行身份验证。 |
ManagedIdentityCredential |
对 Azure 资源的托管标识进行身份验证。 |
WorkloadIdentityCredential |
支持 Kubernetes 上的 Azure AD 工作负载标识 。 |
对服务主体进行身份验证
| 凭据 | 使用情况 | 参考 |
|---|---|---|
CertificateCredential |
使用证书对服务主体进行身份验证。 | 服务主体身份验证 |
ClientAssertionCredential |
使用已签名的客户端断言对服务主体进行身份验证。 | |
ClientSecretCredential |
使用机密对服务主体进行身份验证。 | 服务主体身份验证 |
对用户进行身份验证
| 凭据 | 使用情况 | 参考 |
|---|---|---|
AuthorizationCodeCredential |
使用以前获取的授权代码对用户进行身份验证。 | OAuth2 验证码 |
DeviceCodeCredential |
以交互方式在具有有限 UI 的设备上对用户进行身份验证。 | 设备代码身份验证 |
InteractiveBrowserCredential |
使用默认系统浏览器以交互方式对用户进行身份验证。 | OAuth2 验证码 |
OnBehalfOfCredential |
通过请求链传播委托的用户标识和权限。 | 代理身份验证 |
UsernamePasswordCredential |
使用用户名和密码对用户进行身份验证， (不支持多重身份验证) 。 | 用户名 + 密码身份验证 |
通过开发工具进行身份验证
| 凭据 | 使用情况 | 参考 |
|---|---|---|
AzureCliCredential |
使用 Azure CLI 在开发环境中进行身份验证。 | Azure CLI 身份验证 |
AzureDeveloperCliCredential |
使用 Azure Developer CLI 在开发环境中进行身份验证。 | Azure Developer CLI参考 |
AzurePowerShellCredential |
使用 Azure PowerShell在开发环境中进行身份验证。 | Azure PowerShell身份验证 |
VisualStudioCodeCredential |
当用户登录到 Visual Studio Code Azure 帐户扩展时进行身份验证。 | VS Code Azure 帐户扩展 |
环境变量
可以使用环境变量配置 DefaultAzureCredential 和 EnvironmentCredential。 每种类型的身份验证都需要特定变量的值：
具有机密的服务主体
| 变量名称 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 应用程序的 ID |
AZURE_TENANT_ID |
应用程序的 Azure AD 租户的 ID |
AZURE_CLIENT_SECRET |
应用程序的客户端机密之一 |
具有证书的服务主体
| 变量名称 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 应用程序的 ID |
AZURE_TENANT_ID |
应用程序的 Azure AD 租户的 ID |
AZURE_CLIENT_CERTIFICATE_PATH |
PEM 或 PKCS12 证书文件（包括私钥）的路径 |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
证书文件的密码（如果有） |
用户名和密码
| 变量名称 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 应用程序的 ID |
AZURE_USERNAME |
用户名（通常为电子邮件地址） |
AZURE_PASSWORD |
该用户的密码 |
按上述顺序尝试进行配置。 例如，如果客户端机密和证书的值都存在，则将使用客户端机密。
令牌缓存
令牌缓存是 Azure 标识库提供的一项功能，它允许应用：
- 将令牌缓存在内存中 (默认) 或磁盘上， (选择加入) 。
- 提高复原能力和性能。
- 减少向 Azure AD 发出的获取访问令牌的请求数。
Azure 标识库提供内存中缓存和永久性磁盘缓存。 有关详细信息，请参阅 令牌缓存文档。
故障排除
有关如何诊断各种故障方案的详细信息，请参阅 故障排除指南 。
错误处理。
凭据在由于缺少所需的数据或状态而无法尝试身份验证时引发 CredentialUnavailableError 。 例如，EnvironmentCredential 在其不完整时将引发此异常。
凭据在身份验证失败时会引发 azure.core.exceptions.ClientAuthenticationError。 ClientAuthenticationError 具有 属性 message ，用于描述身份验证失败的原因。 当 由 DefaultAzureCredential 或 ChainedTokenCredential引发时，该消息从链中的每个凭据收集错误消息。
有关处理特定 Azure AD 错误的详细信息，请参阅 Azure AD 错误代码文档。
日志记录
此库使用标准 日志记录 库进行日志记录。 凭据在 INFO 级别记录基本信息，包括 HTTP 会话 (URL、标头等 ) 。 这些日志条目不包含身份验证机密。
默认情况下，未启用详细的调试级别日志记录，包括请求/响应正文和标头值。 可以使用 参数启用 logging_enable 它。 例如：
credential = DefaultAzureCredential(logging_enable=True)
警告：来自凭据的调试级别日志包含敏感信息。 必须保护这些日志，以免危及帐户安全。
后续步骤
客户端库支持
支持 Azure AD 身份验证的 Azure SDK 发布页上 列出的客户端和管理库接受来自此库的凭据。 可以在发布页面链接的文档中详细了解如何使用这些库。
已知问题
此库不支持 Azure AD B2C。
有关其他未解决的问题，请参阅库的 GitHub 存储库。
提供反馈
如果遇到 bug 或有建议， 请提出问题。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。
提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 在所有存储库中执行此操作一次。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。
