Azure Key Vault证书Python客户端库

Azure Key Vault帮助解决以下问题

• 证书管理（本库）- 创建、管理和部署公钥和私钥SSL/TLS证书
• 密钥管理（azure-keyvault-keys）- 创建、存储和控制用于加密数据的密钥的访问
• 密钥管理（azure-keyvault-secrets）- 安全存储和控制访问令牌、密码、证书、API密钥和其他密钥
• 保险库管理（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-certificates 和 azure-identity

pip install azure-keyvault-certificates azure-identity

azure-identity 用于以下示例中的 Azure Active Directory 身份验证。

先决条件

• 一个 Azure 订阅
• Python 3.8或更高版本
• 现有的 Azure Key Vault。如果您需要创建一个，可以使用 Azure CLI 通过以下文档中的步骤进行操作 此文档。

客户端身份验证

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

有关其他身份验证方法及其对应凭证类型的更多信息，请参阅 azure-identity 文档。

创建客户端

配置环境以使用 DefaultAzureCredential 并选择合适的身份验证方法后，您可以通过以下步骤创建证书客户端（将 VAULT_URL 的值替换为您的保管库 URL）

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

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

关键概念

CertificateClient

使用 CertificateClient，您可以从保管库获取证书，创建新证书和现有证书的新版本，更新证书元数据，以及删除证书。您还可以管理证书颁发者、联系人和管理策略。以下示例中展示了这些功能。

示例

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

• 创建证书
• 检索证书
• 更新现有证书的属性
• 删除证书
• 列出证书属性
• 异步操作
• 异步创建证书
• 异步列出证书属性

创建证书

begin_create_certificate 在 Azure Key Vault 中创建证书。如果已存在同名证书，则创建证书的新版本。在创建证书之前，可以创建证书的管理策略或使用默认策略。此方法返回一个长运行操作轮询器。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

如果您想检查证书创建的状态，可以在轮询器上调用 status() 或使用证书名称调用 get_certificate_operation。

检索证书

get_certificate 用于检索存储在密钥保管库中的证书的最新版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version 用于检索证书的特定版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

更新现有证书的属性

update_certificate_properties 用于更新存储在密钥保管库中的证书。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

删除证书

begin_delete_certificate 请求密钥保管库删除证书，返回一个轮询器，允许您等待删除完成。当保管库启用了 软删除 且您希望尽快永久删除证书时，等待非常有用。当禁用 软删除 时，begin_delete_certificate 本身就是永久的。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

列出证书属性

list_properties_of_certificates 列出指定密钥保管库中所有证书的属性。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

异步操作

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

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

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = CertificateClient(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 = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

异步创建证书

create_certificate 创建要存储在Azure密钥保管库中的证书。如果已存在具有相同名称的证书，则创建证书的新版本。在创建证书之前，可以创建证书的管理策略，或者使用默认策略。如果创建成功，则等待 create_certificate 返回创建的证书；如果不成功，则返回 CertificateOperation。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

异步列出证书属性

list_properties_of_certificates 列出客户端保管库中所有证书的属性。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

故障排除

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

通用

密钥保管库客户端引发由 azure-core 定义的异常。例如，如果您尝试获取保管库中不存在的密钥，CertificateClient 将引发 ResourceNotFoundError。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

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

try:
    certificate_client.get_certificate("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.certificates import CertificateClient
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
client = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

还可以为任何单个操作启用网络跟踪日志记录。

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

下一步

Azure SDK for Python的GitHub存储库中提供了一些示例。这些示例提供了Key Vault其他场景的示例代码。

• 创建/获取/更新/删除证书 (异步版本)
• 备份和恢复证书 (异步版本)
• 将PKCS#12 (PFX) 和PEM格式的证书导入到密钥保管库 (异步版本)
• 列出证书 (异步版本)
• 恢复和清除证书 (异步版本)
• 管理证书发行者 (异步版本)
• 管理证书联系人 (异步版本)
• 提取证书的私钥 (异步版本)

其他文档

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

贡献

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

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在所有使用我们的CLA的存储库中执行此操作一次。

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

发布历史

4.8.0 (2024-02-22)

新增功能

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

破坏性更改

这些更改不会影响4.7.0等稳定版本的API。只有针对4.8.0b2等测试版本的代码可能受到影响。

• 删除了CertificateProperties.x509_thumbprint_string。要获取证书的指纹（十六进制），请使用CertificateProperties.x509_thumbprint.hex()或打印CertificateProperties实例。

错误修复

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

其他更改

• 不再支持Python 3.7。请使用Python版本3.8或更高版本。
• asyncio不再由库直接引用 (#33819)
• 密钥保管库API版本7.5现在是默认版本
• 更新最低azure-core版本为1.29.5
• 删除azure-common需求

4.8.0b3 (2023-11-03)

新增功能

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

其他更改

• 密钥保管库API版本 7.5-preview.1 现已设置为默认

4.8.0b2 (2023-07-11)

新增功能

• 添加了 CertificateProperties.x509_thumbprint_string 以返回证书的SHA-1哈希值的十六进制字符串表示形式 (#30166)

4.8.0b1 (2023-05-16)

错误修复

• 在AD FS身份验证过程中发出的令牌请求不再指定错误的 "adfs" 租户ID (#29888)

4.7.0 (2023-03-16)

新增功能

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

错误修复

• KeyVaultCertificate.cer 和 DeletedCertificate.cer 的类型提示现在为 Optional[bytearray] 而不是 Optional[bytes] (#28959)

其他更改

• Python 3.6不再受支持。请使用Python版本3.7或更高版本。
• 密钥保管库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)

错误修复

• 现在在 KeyVaultCertificateIdentifier 的 vault_url 属性中保留端口号 (#24446)

4.4.0 (2022-03-28)

新增功能

• 密钥保管库API版本7.3现在设置为默认
• 在使用 azure-identity 1.8.0 或更高版本时添加了对多租户身份验证的支持 (#20698)

错误修复

• KeyType 现在在声明时忽略大小写，这解决了无法使用SDK检索以非标准大小写创建的密钥保管库密钥的场景 (#22797)

其他更改

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

4.4.0b3 (2022-02-08)

其他更改

• 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
• CertificatePolicy 的 issuer_name 参数现在是可选的

添加

• 添加了类 KeyVaultCertificateIdentifier，它解析出Key Vault返回的完整ID，因此用户可以轻松访问证书的 name、vault_url 和 version。

4.2.1 (2020-09-08)

修复

• 分页方法的正确输入
• 修复了与API版本2016-10-01的不兼容性问题

4.2.0 (2020-08-11)

修复

• 修复了在get_certificate_version期间出现的AttributeError
• import_certificate在未传递policy关键字参数时不再引发AttributeError
• 日志输出中不再隐藏x-ms-keyvault-region和x-ms-keyvault-service-version头部的值

更改

• Key Vault API版本7.1现在是默认版本
• 更新了最小azure-core版本到1.7.0

添加

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

4.2.0b1 (2020-03-10)

• 支持Key Vault API版本7.1-preview (#10124)
  • 向CertificateProperties添加了recoverable_days
  • 添加了标识此包支持的Key Vault版本的ApiVersion枚举

4.1.0 (2020-03-10)

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

4.0.1 (2020-02-11)

• azure.keyvault.certificates定义了__version__
• 更新了msrest的要求为>=0.6.0
• 挑战认证策略需要TLS（#9457）
• 方法不再引发内部错误KeyVaultErrorException（#9690）

4.0.0 (2020-01-08)

• 首个GA版本

4.0.0b7 (2019-12-17)

• 挑战认证策略保留请求选项（#8999）
• 向CertificateOperation添加了vault_url属性
• 从CertificatePolicy中删除了id、expires_on、not_before和recover_level属性
• 从CertificateIssuer中删除了vault_url属性
• 从IssuerProperties中删除了vault_url属性

4.0.0b6 (2019-12-04)

• 更新了msrest的要求为>=0.6.0
• 将get_policy重命名为get_certificate_policy
• 将update_policy重命名为update_certificate_policy
• 将create_contacts重命名为set_contacts
• 将create_issuer和update_issuer的参数admin_details重命名为admin_contacts
• 将所有name参数重命名为包含我们引用的对象的名称。例如，get_certificate的name参数现在是certificate_name
• 将AdministratorDetails重命名为AdministratorContact
• 将CertificatePolicy的ekus属性重命名为enhanced_key_usage
• 将CertificatePolicy的curve属性重命名为key_curve_name
• 将CertificatePolicy的san_upns属性重命名为san_user_principal_names
• 将CertificatePolicy的subject_name属性改为关键字参数，并将其重命名为subject
• 将DeletedCertificate的deleted_date属性重命名为deleted_on
• 从CertificateIssuer中删除了issuer_properties属性，并直接在CertificateIssuer上添加了provider属性
• 将CertificateIssuer的属性admin_details重命名为admin_contacts
• 将CertificateProperties的thumbprint属性重命名为x509_thumbprint
• 添加了包含常用颁发者名称的枚举类WellKnownIssuerNames
• 将SecretContentType枚举类重命名为CertificateContentType

4.0.0b5 (2019-11-01)

• 删除了冗余方法get_pending_certificate_signing_request()。可以通过get_certificate_operation()检索挂起的CSR。

• 将同步方法create_certificate重命名为begin_create_certificate

• 将restore_certificate重命名为restore_certificate_backup

• 将 get_certificate 重命名为 get_certificate_version

• 将 get_certificate_with_policy 重命名为 get_certificate

• 将 list_certificates 重命名为 list_properties_of_certificates

• 将 list_properties_of_issuers 重命名为 list_properties_of_issuers

• 将 list_certificate_versions 重命名为 list_properties_of_certificate_versions

• create_certificate 现在以策略作为必选参数

• 除了 version 以外的所有可选位置参数都已移动到 kwargs

• 将同步方法 delete_certificate 重命名为 begin_delete_certificate

• 将同步方法 recover_certificate 重命名为 begin_recover_deleted_certificate

• 将异步方法 recover_certificate 重命名为 recover_deleted_certificate

• 同步方法 begin_delete_certificate 和异步的 delete_certificate 现在返回返回 DeletedCertificate 的轮询器

• 同步方法 begin_recover_deleted_certificate 和异步的 recover_deleted_certificate 现在返回返回 KeyVaultCertificate 的轮询器

• 将枚举 ActionType 重命名为 CertificatePolicyAction

• 将 Certificate 重命名为 KeyVaultCertificate

• 将 Contact 重命名为 CertificateContact

• 将 Issuer 重命名为 CertificateIssuer

• 将 CertificateError 重命名为 CertificateOperationError

• 将 CertificateProperties 和 CertificatePolicy 的 expires 属性重命名为 expires_on

• 将 CertificateProperties、CertificatePolicy 和 CertificateIssuer 的 created 属性重命名为 created_on

• 将 CertificateProperties、CertificatePolicy 和 CertificateIssuer 的 updated 属性重命名为 updated_on

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

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

• CertificatePolicy 现在有一个公共类方法 get_default，允许用户获取默认的 CertificatePolicy

• 现在可以在客户端级别正确启用日志记录

4.0.0b4 (2019-10-08)

• 枚举 JsonWebKeyCurveName 和 JsonWebKeyType 分别重命名为 KeyCurveName 和 KeyType

• create_certificate 的异步和同步版本现在在创建成功时返回创建的 Certificate，如果失败，则返回 CertificateOperation

• Certificate 现在具有属性 properties，该属性包含证书的某些属性，例如 version。这改变了 Certificate 类型的形状，因为某些 Certificate 属性（如 version）必须通过 properties 属性来访问。

• update_certificate 已重命名为 update_certificate_properties

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

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

4.0.0b3 (2019-09-11)

4.0.0b3 是我们创建用于 Azure Key Vault 证书的易于使用且具有 Pythonic 风格的客户端库的第一个预览版。

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

azure-keyvault 的重大更改

• 按功能划分的包
  • azure-keyvault-certificates 包含证书操作客户端
• 客户端实例的范围限于密钥库（一个实例仅与一个密钥库交互）
• 使用 azure-identity 凭据进行身份验证
  • 请参阅此软件包的文档，以及Azure Identity文档以获取更多信息。

新功能

• 支持分布式跟踪框架OpenCensus
• 支持Python 3.5.3+上的异步API
  • azure.keyvault.certificates.aio命名空间包含azure.keyvault.certificates中同步客户端的异步等效版本
  • 异步客户端默认使用aiohttp进行传输。有关使用其他传输方式的更多信息，请参阅azure-core文档。