适用于 Python 的 Azure 标识客户端库中的凭据链

Azure 标识客户端库提供凭据—实现 Azure Core 库的 TokenCredential 协议的公共类。 凭据表示从 Microsoft Entra ID 获取访问令牌的独特身份验证流。 这些凭证可以链接在一起，形成要尝试的身份验证机制的有序序列。

链接凭据的工作原理

在运行时，凭证链尝试使用序列的第一个凭据进行身份验证。 如果该凭据无法获取访问令牌，则会尝试序列中的下一个凭据，以此类推，直到成功获取访问令牌。 以下序列图说明了这种行为：

为何使用凭据链

链接凭据可提供以下优势：

• 环境感知：根据应用运行的环境自动选择最合适的凭据。 如果没有它，必须编写如下所示的代码：

  # Set up credential based on environment (Azure or local development)
  if os.getenv("WEBSITE_HOSTNAME"):
      credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
  else:
      credential = AzureCliCredential()
  

• 无缝转换：应用可以在不更改身份验证代码的情况下从本地开发迁移到暂存或生产环境。

• 改进了复原能力：包括一个回退机制，当前一个凭据无法获取访问令牌时，该机制会移动到下一个凭据。

如何选择链接凭据

凭据链接有两种不同的理念：

• “拆解”链：从预配置链开始，并排除不需要的内容。 有关此方法，请参阅 DefaultAzureCredential 概述部分。
• “构建”链：从空链开始，仅包含所需的内容。 有关此方法，请参阅 ChainedTokenCredential 概述部分。

DefaultAzureCredential 概述

DefaultAzureCredential 是一个固定的预配置凭据链。 它旨在支持许多环境，以及最常见的身份验证流和开发人员工具。 在图形形式中，基础链如下所示：

DefaultAzureCredential 尝试凭据的顺序如下。

最简单的形式是，可以使用 DefaultAzureCredential 的无参数版本，如下所示：

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

# Acquire a credential object
credential = DefaultAzureCredential()

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

如何自定义 DefaultAzureCredential

若要从 DefaultAzureCredential 中删除凭据，请使用相应的前缀为 exclude 的关键字参数。 例如：

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

在前面的代码示例中，从凭证链中删除了 EnvironmentCredential 和 WorkloadIdentityCredential。 因此，要尝试的第一个凭据是 ManagedIdentityCredential。 修改后的链如下所示：

随着更多以 exclude 为前缀的关键字参数设置为 True（配置了凭据排除），使用 DefaultAzureCredential 的优势逐渐减弱。 在这种情况下，ChainedTokenCredential 是更好的选择，并且需要更少的代码。 为了说明，这两个代码示例的行为方式相同：

credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id=user_assigned_client_id),
    AzureCliCredential()
)

ChainedTokenCredential 概述

ChainedTokenCredential 是一个空链，可向其添加凭据以满足应用的需求。 例如：

credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id=user_assigned_client_id),
    AzureCliCredential()
)

前面的代码示例创建了一个由两个凭据组成的定制凭据链。 首先尝试 ManagedIdentityCredential 的用户分配的托管标识变体，然后在必要时尝试 AzureCliCredential。 在图形形式中，链如下所示：

DefaultAzureCredential 的使用指南

DefaultAzureCredential 无疑是开始使用 Azure 标识客户端库的最简单方法，但随之而来的是权衡。 将应用部署到 Azure 后，应了解应用的身份验证要求。 因此，强烈建议从 DefaultAzureCredential 迁移到以下解决方案之一：

• 特定的凭据实现，例如 ManagedIdentityCredential。
• 针对运行应用的 Azure 环境优化的精简版 ChainedTokenCredential 实现。

原因如下：

• 调试挑战：身份验证失败时，调试和识别违规凭据可能很困难。 必须启用日志记录，才能查看从一个凭据到下一个凭据的进度以及每个凭据的成功/失败状态。 有关详细信息，请参阅调试链接凭据。
• 性能开销：按顺序尝试多个凭据的过程可能会导致性能开销。 例如，在本地开发计算机上运行时，托管标识不可用。 因此，ManagedIdentityCredential 在本地开发环境中总是失败，除非通过其相应的 exclude 前缀属性明确禁用。
• 不可预知的行为：DefaultAzureCredential检查是否存在某些环境变量。 有可能有人可以在主机上的系统级别添加或修改这些环境变量。 这些更改在全局范围内适用，因此会在该计算机上运行的任何应用中改变 DefaultAzureCredential 在运行时的行为。

调试链接凭据

若要诊断意外问题或了解链接凭据正在执行的操作，请在应用中启用日志记录。 （可选）将日志筛选为仅从 Azure 标识客户端库发出的那些事件。 例如：

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

为了便于说明，假设使用 DefaultAzureCredential 的无参数形式对 Blob 存储帐户的请求进行身份验证。 应用在本地开发环境中运行，开发人员使用 Azure CLI 向 Azure 进行身份验证。 还假设日志记录级别设置为 logging.DEBUG。 运行应用程序时，输出中会出现以下相关条目：

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

在前面的输出中，请注意：

• EnvironmentCredential、ManagedIdentityCredential 和 SharedTokenCacheCredential 每个项都未能按该顺序获取 Microsoft Entra 访问令牌。
• AzureCliCredential.get_token 调用成功，输出还表明 DefaultAzureCredential 从 AzureCliCredential 获取了一个令牌。 由于 AzureCliCredential 成功，因此未尝试超出它的凭据。