Azure Key Vault Secrets Python客户端库

Azure Key Vault有助于解决以下问题

• 秘密管理（本库） - 安全存储和控制访问令牌、密码、证书、API密钥和其他秘密
• 加密密钥管理（azure-keyvault-keys） - 创建、存储和控制用于加密数据的密钥的访问
• 证书管理（azure-keyvault-certificates） - 创建、管理和部署公共和私有SSL/TLS证书
• 保险库管理（azure-keyvault-administration） - 基于角色的访问控制（RBAC），以及保险库级别的备份和还原选项

源代码 | 包（PyPI） | 包（Conda） | API 参考文档 | 产品文档 | 示例

免责声明

Azure SDK Python 包对 Python 2.7 的支持已于 2022 年 1 月 1 日结束。有关更多信息及问题，请参阅 https://github.com/Azure/azure-sdk-for-python/issues/20691。 使用此包需要 Python 3.8 或更高版本。有关更多详细信息，请参阅 Azure SDK for Python 版本支持策略。

入门

安装包

使用 pip 安装 azure-keyvault-secrets 和 azure-identity

pip install azure-keyvault-secrets azure-identity

azure-identity 用于 Azure Active Directory 认证，如下所示。

先决条件

• 一个 Azure 订阅
• Python 3.8 或更高版本
• 现有的 Azure Key Vault。如果您需要创建一个，可以使用 Azure CLI 创建，具体步骤请参阅 此文档。

认证客户端

为了与 Azure Key Vault 服务交互，您需要一个 SecretClient 实例、一个 保管库 URL 和一个凭据对象。本文档展示了使用 DefaultAzureCredential，这对于大多数场景（包括本地开发和生产环境）都是合适的。我们建议在生产环境中使用 托管标识 进行认证。

有关其他认证方法和相应凭据类型的更多信息，请参阅 azure-identity 文档。

创建客户端

在为 DefaultAzureCredential 配置环境并使用适当的认证方法后，您可以通过以下步骤创建一个密钥客户端（将 VAULT_URL 的值替换为您的保管库 URL）

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)

注意：对于异步客户端，请导入 azure.keyvault.secrets.aio 的 SecretClient。

关键概念

密钥

密钥由一个密钥值及其关联的元数据和管理工作信息组成。此库将密钥值作为字符串处理，但 Azure Key Vault 并不以此方式存储。有关密钥以及 Key Vault 如何存储和管理密钥的更多信息，请参阅 密钥保管库文档。

SecretClient 可在保管库中设置密钥值、更新密钥元数据以及删除密钥，如下面的示例所示。

示例

本节包含涵盖常见任务的代码片段

• 设置密钥
• 检索密钥
• 更新密钥元数据
• 删除密钥
• 列出密钥
• 异步 API
• 异步创建密钥
• 异步列出密钥

设置密钥

set_secret 创建新的密钥并更改现有密钥的值。如果不存在具有给定名称的密钥，set_secret 将使用该名称和给定值创建一个新的密钥。如果该名称正在使用中，set_secret 将创建该密钥的新版本，并使用给定值。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

检索密钥

get_secret 从密钥库中检索之前存储的密钥。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")

print(secret.name)
print(secret.value)

更新密钥元数据

update_secret_properties 更新密钥的元数据。它不能更改密钥的值；请使用 set_secret 来设置密钥的值。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"

# We will also disable the secret for further use

updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)

print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)

删除密钥

begin_delete_secret 请求密钥库删除密钥，返回一个轮询器，允许您等待删除完成。当启用 软删除 且您希望尽快清除（永久删除）密钥时，等待很有帮助。当禁用 软删除 时，begin_delete_secret 本身就是永久的。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

列出密钥

list_properties_of_secrets 列出客户端密钥库中所有密钥的属性。此列表不包括密钥的值。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

异步 API

此库包含一套完整的异步API。要使用它们，您必须首先安装异步传输，例如 aiohttp。有关更多信息，请参阅 azure-core 文档。

当不再需要时，应关闭异步客户端和凭据。这些对象是异步上下文管理器，并定义异步 close 方法。例如

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

异步创建密钥

set_secret 使用指定的可选参数在密钥库中创建密钥。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

secret = await secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

异步列出密钥

list_properties_of_secrets 列出客户端密钥库中所有密钥的属性。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

async for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

故障排除

有关如何诊断各种失败场景的详细信息，请参阅 azure-keyvault-secrets 的 故障排除指南。

通用

密钥库客户端抛出在 azure-core 中定义的异常。例如，如果您尝试获取密钥库中不存在的密钥，SecretClient 会抛出 ResourceNotFoundError

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    secret_client.get_secret("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

日志记录

此库使用标准 logging 库进行日志记录。HTTP会话的基本信息（URL、标题等）在 INFO 级别记录。

可以使用 logging_enable 参数在客户端上启用详细的 DEBUG 级别日志记录，包括请求/响应体和未编辑的标题。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
secret_client = SecretClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

类似地，logging_enable 可以启用单个操作的详细日志记录，即使它没有为客户端启用也是如此。

secret_client.get_secret("my-secret", logging_enable=True)

下一步

Azure SDK for Python GitHub存储库中提供了一些示例。这些示例提供了额外的密钥库场景的示例代码。

• 创建/获取/更新/删除密钥 (异步版本)
• 密钥的基本列表操作 (异步版本)
• 备份和恢复密钥 (异步版本)
• 恢复和清除密钥 (异步版本)

其他文档

有关Azure Key Vault的更多详细文档，请参阅API参考文档。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权并将实际授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人会自动确定您是否需要提供CLA，并适当地修饰PR（例如，标签，注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的CLA的仓库中进行一次。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com以获取任何其他问题或评论。

发布历史

4.8.0 (2024-02-22)

新增功能

• 添加了对服务API版本7.5的支持

修复了错误

• (从4.8.0b1开始)在进行AD FS身份验证期间发出的令牌请求不再指定错误的“adfs”租户ID (#29888)

其他更改

• 不再支持Python 3.7。请使用Python版本3.8或更高版本。
• asyncio不再直接引用库 (#33819)
• 将最小azure-core版本更新到1.29.5
• 取消了对azure-common的要求

4.8.0b2 (2023-11-03)

新增功能

• 添加了对服务API版本7.5-preview.1的支持

其他更改

• Key Vault API版本7.5-preview.1现在是默认版本

4.8.0b1 (2023-05-16)

修复了错误

• 在进行AD FS身份验证期间发出的令牌请求不再指定错误的“adfs”租户ID (#29888)

4.7.0 (2023-03-16)

新增功能

• 添加了对服务API版本7.4的支持
• 每个客户端都有一个send_request方法，可以用来通过客户端现有的管道发送自定义请求 (#25172)

其他更改

• 不再支持Python 3.6。请使用Python版本3.7或更高版本。
• Key Vault API版本7.4现在是默认版本
• 将最小azure-core版本更新到1.24.0
• 取消了对msrest的要求
• 添加了对isodate>=0.6.1的要求（《isodate》由《msrest》需要）
• 添加了对typing-extensions>=4.0.1的要求

4.6.0 (2022-09-19)

破坏性更改

• 客户端会验证挑战资源与保管库域名匹配。这可能会影响少数客户，他们可以通过将verify_challenge_resource=False提供给客户端构造函数来禁用此功能。有关更多信息，请参阅https://aka.ms/azsdk/blog/vault-uri。

4.5.1 (2022-08-11)

其他更改

• 文档改进（《#25039》）

4.5.0b1 (2022-06-07)

修复了错误

• 现在在KeyVaultSecretIdentifier的vault_url属性中保留端口号（《#24446》）

4.4.0 (2022-03-28)

新增功能

• Key Vault API版本7.3现在是默认版本
• 在使用 azure-identity 1.8.0 或更高版本时，增加了多租户身份验证支持（#20698）
• （从 4.4.0b3 开始）为 SecretProperties 添加了 managed 属性

其他更改

• （从 4.4.0b3 开始）不再支持 Python 2.7。请使用 Python 版本 3.6 或更高版本。
• 将最低 azure-core 版本更新到 1.20.0
• （从 4.4.0b2 开始）为了支持多租户身份验证，挑战身份验证请求期间 get_token 调用现在将传递一个 tenant_id 关键字参数（#20698）。有关如何集成此参数的详细信息，请参阅 https://aka.ms/azsdk/python/identity/tokencredential，如果 get_token 由自定义凭据实现。

4.4.0b3（2022-02-08）

新增功能

• 为 SecretProperties 添加了 managed 属性

其他更改

• 不再支持 Python 2.7。请使用 Python 版本 3.6 或更高版本。
• （从 4.4.0b2 开始）为了支持多租户身份验证，挑战身份验证请求期间 get_token 调用现在将传递一个 tenant_id 关键字参数（#20698）

4.4.0b2（2021-11-11）

新增功能

• 在使用 azure-identity 1.7.1 或更高版本时，增加了多租户身份验证支持（#20698）

其他更改

• 将最低 azure-core 版本更新到 1.15.0

4.4.0b1（2021-09-09）

新增功能

• 密钥保管库 API 版本 7.3-preview 现已默认启用

其他更改

• 更新了类型提示以修复 mypy 错误（#19158）

4.3.0 (2021-06-22)

这是支持 Python 3.5 的最后一个版本。下一个版本将需要 Python 2.7 或 3.6+。

已修复

• 为异步分页方法正确设置类型

已更改

• 密钥保管库 API 版本 7.2 现已默认启用
• 将最低 msrest 版本更新到 0.6.21

已添加

• 添加了类 KeyVaultSecretIdentifier，该类可以解析 Key Vault 返回的完整 ID，因此用户可以轻松访问密钥的 name、vault_url 和 version。

4.2.0 (2020-08-11)

已修复

• 日志输出中不再省略 x-ms-keyvault-region 和 x-ms-keyvault-service-version 标头的值

已更改

• 密钥保管库 API 版本 7.1 现已默认启用
• 将最低 azure-core 版本更新到 1.7.0

已添加

• 在构造时，客户端通过可选关键字参数 custom_hook_policy 接受 CustomHookPolicy
• 所有客户端请求都包括在头部 x-ms-client-request-id 中的唯一 ID
• 为多 api 支持，依赖于 azure-common

4.2.0b1（2020-03-10）

• 支持密钥保管库 API 版本 7.1-preview（#10124）
  • 为 CertificateProperties 添加了 recoverable_days
  • 添加了标识此包支持的密钥保管库版本的 ApiVersion 枚举

4.1.0 (2020-03-10)

• SecretClient 实例有一个 close 方法，用于关闭打开的套接字。用作上下文管理器时，SecretClient 在退出时关闭打开的套接字。（#9906）
• 操作完成后，轮询器不再休眠（#9991）

4.0.1 (2020-02-11)

• azure.keyvault.secrets 定义了 __version__
• 挑战身份验证策略保留请求选项（#8999）
• 将 msrest 的要求更新为 >=0.6.0
• 挑战身份验证策略需要 TLS（#9457）
• 方法不再引发内部错误 KeyVaultErrorException（#9690）

4.0.0 (2019-10-31)

破坏性更改

• 将两个方法的可选参数移动到 kwargs 中（文档 详细说明了新的关键字参数）
  • set_secret 现在具有位置参数 name 和 value
  • update_secret_properties 现在具有位置参数 name 和（可选）version
• 将 list_secrets 重命名为 list_properties_of_secrets
• 将list_secret_versions重命名为list_properties_of_secret_versions
• 将同步方法delete_secret重命名为begin_delete_secret
• 同步方法begin_delete_secret和异步delete_secret现在返回返回DeletedSecret的pollers
• 将Secret重命名为KeyVaultSecret
• KeyVaultSecret属性created、expires和updated重命名为created_on、expires_on和updated_on
• SecretClient的vault_endpoint参数已重命名为vault_url
• 在所有模型中，属性vault_endpoint已重命名为vault_url

4.0.0b4 (2019-10-08)

破坏性更改

• Secret现在具有属性properties，该属性包含秘密的某些属性，例如version。这改变了返回的Secret类型，因为Secret的某些属性（如version）必须通过properties属性来访问。

• update_secret已重命名为update_secret_properties

• SecretClient的vault_url参数已重命名为vault_endpoint

• 在所有模型中，属性vault_url已重命名为vault_endpoint

修复和改进

• list_secrets和list_secret_versions返回正确类型

4.0.0b3 (2019-09-11)

此版本仅包含内部更改。

4.0.0b2 (2019-08-06)

破坏性更改

• 为了准备重构配置API，已从公共API中删除了azure.core.Configuration。静态create_config方法已重命名为_create_config，将在未来版本中删除。
• 此版本的库需要azure-core 1.0.0b2
  • 如果您以后想回滚到需要azure-core 1.0.0b1的版本，无论是此版本还是其他Azure SDK库，您必须明确安装azure-core 1.0.0b1。例如：pip install azure-core==1.0.0b1 azure-keyvault-secrets==4.0.0b1

新功能

• 分布式跟踪框架OpenCensus现在受支持
• 增加了基于HTTP挑战的认证支持，允许客户端与主权云中的保管库进行交互。

4.0.0b1 (2019-06-28)

4.0.0b1是我们努力创建一个用户友好且符合Python风格的Azure Key Vault客户端库的第一个预览版。有关其他Azure SDK库预览版本的信息，请访问https://aka.ms/azure-sdk-preview1-python。

此库不是直接替换azure-keyvault的。使用该库的应用程序需要代码更改才能使用azure-keyvault-secrets。此包的文档和示例展示了新的API。

从azure-keyvault的重大更改

• 按功能范围打包
  • azure-keyvault-secrets包含秘密操作的客户端，azure-keyvault-keys包含密钥操作的客户端
• 客户端实例的范围是保管库（一个实例只与一个保管库交互）
• 支持Python 3.5.3+的异步API
  • azure.keyvault.secrets.aio命名空间包含与azure.keyvault.secrets中的同步客户端异步等效的客户端
• 使用azure-identity凭据进行认证
  • 有关更多信息，请参阅此包的文档和Azure Identity文档

此库中未实现azure-keyvault的功能

• 证书管理API
• 国家云支持。此版本支持公共全局云保管库，例如 https://{vault-name}.vault.azure.net