快速入门:适用于 Python 的 Azure Key Vault 证书客户端库

适用于 Python 的 Azure Key Vault 证书客户端库入门。 请按照以下步骤安装程序包并试用基本任务的示例代码。 通过使用 Key Vault 存储证书,可以避免在代码中存储证书,从而提高应用的安全性。

API 参考文档 | 库源代码 | 包(Python 包索引)

先决条件

本快速入门假设在 Linux 终端窗口中运行 Azure CLIAzure PowerShell

设置本地环境

本快速入门结合使用 Azure 标识库和 Azure CLI 或 Azure PowerShell,向 Azure 服务验证用户身份。 开发人员还可以使用 Visual Studio 或 Visual Studio Code 来验证其调用。 有关详细信息,请参阅使用 Azure 标识客户端库对客户端进行身份验证

登录 Azure

  1. 运行 login 命令。

    az cloud set -n AzureChinaCloud
    az login
    # az cloud set -n AzureCloud   //means return to Public Azure.
    

    如果 CLI 可以打开默认浏览器,它将这样做并加载 Azure 登录页。

    否则,请在 https://login.partner.microsoftonline.cn/common/oauth2/deviceauth 处打开浏览器页,然后输入终端中显示的授权代码。

  2. 在浏览器中使用帐户凭据登录。

安装包

  1. 在终端或命令提示符中,创建合适的项目文件夹,然后创建并激活 Python 虚拟环境,如使用 Python 虚拟环境中所述

  2. 安装 Microsoft Entra 标识库:

    pip install azure.identity
    
  3. 安装 Key Vault 证书客户端库:

    pip install azure-keyvault-certificates
    

创建资源组和 Key Vault

  1. 使用 az group create 命令以创建资源组:

    az group create --name myResourceGroup --location chinaeast
    

    如果愿意,你可以将“chinaeast”更改为离你更近的位置。

  2. 使用 az keyvault create 创建密钥保管库:

    az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup
    

    <your-unique-keyvault-name> 替换为在整个 Azure 中均唯一的名称。 通常使用个人或公司名称以及其他数字和标识符。

设置 KEY_VAULT_NAME 环境变量

脚本将使用分配给 KEY_VAULT_NAME 环境变量的值作为密钥保管库的名称。 因此,必须使用以下命令设置此值:

export KEY_VAULT_NAME=<your-unique-keyvault-name>

授予对 Key Vault 的访问权限

若要通过基于角色的访问控制 (RBAC) 授予应用程序对密钥保管库的权限,请使用 Azure CLI 命令 az role assignment create 分配角色。

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

<app-id><subscription-id><resource-group-name><your-unique-keyvault-name> 替换为实际值。 <app-id> 是在 Azure Entra 中注册的应用程序的应用程序(客户端)ID。

创建示例代码

使用适用于 Python 的 Azure Key Vault 证书客户端库管理证书。 以下代码示例演示了如何创建客户端、设置证书、检索证书和删除证书。

创建包含此代码的名为 kv_certificates.py 的文件。

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

keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = "https://" + keyVaultName + ".vault.azure.cn"

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

certificateName = input("Input a name for your certificate > ")

print(f"Creating a certificate in {keyVaultName} called '{certificateName}' ...")

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

print(" done.")

print(f"Retrieving your certificate from {keyVaultName}.")

retrieved_certificate = client.get_certificate(certificateName)

print(f"Certificate with name '{retrieved_certificate.name}' was found'.")
print(f"Deleting your certificate from {keyVaultName} ...")

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

print(" done.")

运行代码

确保上一部分中的代码位于名为 kv_certificates.py 的文件中。 然后,使用以下命令运行代码:

python kv_certificates.py

代码详细信息

进行身份验证并创建客户端

对大多数 Azure 服务的应用程序请求必须获得授权。 要在代码中实现与 Azure 服务的无密码连接,建议使用 Azure 标识客户端库提供的 DefaultAzureCredential 类。 DefaultAzureCredential 支持多种身份验证方法,并确定应在运行时使用哪种方法。 通过这种方法,你的应用可在不同环境(本地与生产)中使用不同的身份验证方法,而无需实现特定于环境的代码。

在本快速入门中,DefaultAzureCredential 使用登录到 Azure CLI 的本地开发用户的凭据对密钥保管库进行身份验证。 将应用程序部署到 Azure 时,相同的 DefaultAzureCredential 代码可以自动发现并使用分配给应用服务、虚拟机或其他服务的托管标识。 有关详细信息,请参阅托管标识概述

在示例代码中,密钥保管库的名称将扩展为密钥保管库 URI,格式为 https://\<your-key-vault-name>.vault.azure.cn

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

保存证书

获取密钥保管库的客户端对象后,可以使用 begin_create_certificate 方法来创建证书:

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

此处,证书要求使用 CertificatePolicy get_default 方法来获取策略。

调用 begin_create_certificate 方法会生成对密钥保管库的 Azure REST API 的异步调用。 异步调用会返回一个轮询器对象。 若要等待操作的结果,请调用轮询器的 result 方法。

Azure 在处理请求时,会使用你提供给客户端的凭据对象,对调用方的标识(服务主体)进行身份验证。

检索证书

若要从 Key Vault 读取证书,请使用 get_certificate 方法:

retrieved_certificate = client.get_certificate(certificateName)

还可以使用 Azure CLI 命令 az keyvault certificate show 或 Azure PowerShell cmdlet Get-AzKeyVaultCertificate 来验证是否设置了证书

删除证书

若要删除证书,请使用 begin_delete_certificate 方法:

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

begin_delete_certificate 方法是异步方法,将返回一个轮询器对象。 调用轮询器的 result 方法等待其完成。

可以使用 Azure CLI 命令 az keyvault certificate show 或 Azure PowerShell cmdlet Get-AzKeyVaultCertificate 来验证是否已删除证书。

证书删除后,会在一段时间内保持已删除但可恢复状态。 如果再次运行该代码,请使用其他证书名称。

清理资源

如果还想试验机密密钥,可以重复使用本文中创建的 Key Vault。

否则,当完成本文中创建的资源后,请使用以下命令删除资源组及其包含的所有资源:

az group delete --resource-group myResourceGroup

后续步骤