你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 Python 的 Azure 密钥保管库 管理客户端库 - 版本 4.3.0
注意：管理库仅适用于托管 HSM - 面向密钥保管库的函数将失败。
Azure Key Vault 有助于解决以下问题：
- 保管库管理 (此库) - 基于角色的访问控制 (RBAC) ，以及保管库级备份和还原选项
- 加密密钥管理 (azure-keyvault-keys) - 创建、存储和控制对用于加密数据的密钥的访问
- 机密管理 (azure-keyvault-secrets) - 安全地存储和控制对令牌、密码、证书、API 密钥和其他机密的访问
- 证书管理 (azure-keyvault-certificates) - 创建、管理和部署公共和专用 SSL/TLS 证书
源代码 | 包 (PyPI) | 包 (Conda) | API 参考文档 | 产品文档 | 样品
免责声明
对 Python 2.7 的 Azure SDK Python 包支持已于 2022 年 1 月 1 日结束。 有关详细信息和问题，请参阅 https://github.com/Azure/azure-sdk-for-python/issues/20691.使用此包需要 Python 3.7 或更高版本。有关更多详细信息，请参阅 Azure SDK for Python 版本支持策略。
入门
安装包
使用 pip 安装 azure-keyvault-administration 和 azure-identity：
pip install azure-keyvault-administration azure-identity
azure-identity 用于 Azure Active Directory 身份验证，如下所示。
先决条件
- Azure 订阅
- Python 3.7 或更高版本
- 现有的密钥保管库托管 HSM。 如果需要创建一个，可以使用 Azure CLI 执行 本文档中的步骤。
验证客户端
为了与 Azure 密钥保管库 服务交互，需要 KeyVaultAccessControlClient 或 KeyVaultBackupClient 的实例，以及保管库 url (Azure 门户) 中可能显示为“DNS 名称”和凭据对象。 本文档演示如何使用适用于大多数方案（包括本地开发和生产环境）的 DefaultAzureCredential。 建议使用 托管标识 在生产环境中进行身份验证。
有关其他身份验证方法及其相应凭据类型的详细信息，请参阅 azure-identity 文档。
创建 KeyVaultAccessControlClient
将 DefaultAzureCredential 的环境配置为使用适当的身份验证方法后，可以执行以下操作来创建访问控制客户端 (将 的值 vault_url 替换为托管 HSM 的 URL) ：
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
注意： 对于异步客户端，请改为导入
azure.keyvault.administration.aio的KeyVaultAccessControlClient。
创建 KeyVaultBackupClient
将 DefaultAzureCredential 的环境配置为使用合适的身份验证方法后，可以执行以下操作来创建备份客户端 (将 的值 vault_url 替换为托管 HSM 的 URL) ：
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
注意： 对于异步客户端，请改为导入
azure.keyvault.administration.aio的KeyVaultBackupClient。
创建 KeyVaultSettingsClient
为 DefaultAzureCredential 配置环境以使用合适的身份验证方法后，可以执行以下操作来创建设置客户端 (将 的值 vault_url 替换为托管 HSM 的 URL) ：
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient
credential = DefaultAzureCredential()
client = KeyVaultSettingsClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
注意： 对于异步客户端，请改为导入
azure.keyvault.administration.aio的KeyVaultSettingsClient。
关键概念
角色定义
角色定义定义可以执行的操作，例如读取、写入和删除。 它还可以定义从允许的操作中排除的操作。
角色定义指定为角色分配的一部分。
角色分配
角色分配是角色定义与服务主体的关联。 可以创建、列出、单独提取和删除它们。
KeyVaultAccessControlClient
管理 KeyVaultAccessControlClient 角色定义和角色分配。
KeyVaultBackupClient
KeyVaultBackupClient执行完整密钥备份、完整密钥还原和选择性密钥还原。
KeyVaultSettingsClient
管理 KeyVaultSettingsClient 托管 HSM 帐户设置。
示例
本部分包含涵盖常见任务的代码片段：
- 访问控制
- 备份和还原
列出所有角色定义
列出可用于分配的角色定义。
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)
for definition in role_definitions:
print(definition.id)
print(definition.role_name)
print(definition.description)
设置、获取和删除角色定义
set_role_definition 可用于创建自定义角色定义或使用指定名称更新现有定义。
import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
KeyVaultAccessControlClient,
KeyVaultDataAction,
KeyVaultPermission,
KeyVaultRoleScope
)
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)
# update the custom role definition
permissions = [
KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)
# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
列出所有角色分配
在下一个 代码片段中创建新角色分配之前，请列出所有当前角色分配：
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)
for assignment in role_assignments:
print(assignment.name)
print(assignment.principal_id)
print(assignment.role_definition_id)
创建、获取和删除角色分配
将角色分配给服务主体。 这需要角色定义 ID 和服务主体对象 ID。 可以使用前者的角色定义检索列表中的 ID，以及上述代码片段中为后者检索到的列表中的分配principal_id。
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"
# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
执行完整密钥备份
备份整个密钥集合。 完整密钥备份的后备存储是使用共享访问签名身份验证的 Blob 存储容器。
有关使用 BlobServiceClient创建 SAS 令牌的详细信息，请参阅 此处的示例。
或者，可以在 存储资源管理器
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>" # replace with a sas token to your storage account
# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()
# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)
执行完整密钥还原
从备份还原整个密钥集合。 完整密钥还原的数据源是使用共享访问签名身份验证访问的存储 Blob。
还需要azure_storage_blob_container_uri上述代码片段中的 。
有关使用 BlobServiceClient创建 SAS 令牌的详细信息，请参阅 此处的示例。
或者，可以在 存储资源管理器
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
sas_token = "<your-sas-token>" # replace with a sas token to your storage account
# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"
# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()
故障排除
有关如何诊断各种故障方案的详细信息，azure-keyvault-administration请参阅故障排除指南。
常规
密钥保管库客户端会引发 azure-core 中定义的异常。 例如，如果尝试获取不存在的角色分配，KeyVaultAccessControlClient 会引发 ResourceNotFoundError：
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
try:
client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
管理库中的客户端只能用于在托管 HSM 上执行操作，因此尝试在密钥保管库上执行此操作将引发错误。
后续步骤
Azure SDK for Python GitHub 存储库中提供了多个示例。 这些示例提供了其他密钥保管库方案的示例代码： |文件 |说明 | |-------------|-------------| |access_control_operations.py |创建/更新/删除角色定义和角色分配 | |access_control_operations_async.py |使用异步客户端创建/更新/删除角色定义和角色分配 | |backup_restore_operations.py |完整备份和还原 | |backup_restore_operations_async.py |使用异步客户端进行完整备份和还原 | |settings_operations.py |列出和更新密钥保管库设置 | |settings_operations_async.py |使用异步客户端列出和更新密钥保管库设置 |
其他文档
有关 Azure 密钥保管库的更多文档，请参阅 API 参考文档。
有关托管 HSM 的更多文档，请参阅 服务文档。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。
提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈