你当前正在访问 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。