Azure Key Vault Administration client library for Python

注意： 管理库仅与 托管HSM 兼容 - 针对Key Vault的功能将失败。

Azure Key Vault 帮助解决以下问题

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

源代码 | 软件包（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-administration 和 azure-identity

pip install azure-keyvault-administration azure-identity

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

先决条件

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

客户端认证

为了与 Azure Key Vault 服务交互，您需要一个 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

MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url=MANAGED_HSM_URL, credential=credential)

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

创建 KeyVaultBackupClient

配置环境以使用 DefaultAzureCredential 以使用合适的认证方法后，您可以执行以下操作来创建一个备份客户端（将 vault_url 的值替换为您托管 HSM 的 URL）

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url=MANAGED_HSM_URL, credential=credential)

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

创建 KeyVaultSettingsClient

在为DefaultAzureCredential配置适合的认证方法后，您可以使用以下步骤创建设置客户端（将vault_url的值替换为您管理的HSM的URL）

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient

MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
credential = DefaultAzureCredential()
client = KeyVaultSettingsClient(vault_url=MANAGED_HSM_URL, credential=credential)

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

关键概念

角色定义

角色定义定义了可以执行的操作，例如读取、写入和删除。它还可以定义排除在允许的操作之外的操作。

角色定义是角色分配的一部分。

角色分配

角色分配是将角色定义与服务主体关联起来的操作。可以创建、列出、单独获取和删除它们。

KeyVaultAccessControlClient

KeyVaultAccessControlClient管理角色定义和角色分配。

KeyVaultBackupClient

KeyVaultBackupClient执行完整密钥备份、完整密钥还原和选择密钥还原。

KeyVaultSettingsClient

KeyVaultSettingsClient管理托管HSM账户设置。

示例

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

• 访问控制
  • 列出所有角色定义
  • 设置、获取和删除角色定义
  • 列出所有角色分配
  • 创建、获取和删除角色分配
• 备份和还原
  • 执行完整密钥备份
  • 执行完整密钥还原
  • 执行选择密钥还原

列出所有角色定义

list_role_definitions可以由KeyVaultAccessControlClient使用，以列出可用于分配的角色定义。

from azure.keyvault.administration import KeyVaultRoleScope

role_definitions = client.list_role_definitions(scope=KeyVaultRoleScope.GLOBAL)
for definition in role_definitions:
    print(f"Role name: {definition.role_name}; Role definition name: {definition.name}")

设置、获取和删除角色定义

set_role_definition可以由KeyVaultAccessControlClient使用，要么创建一个自定义的角色定义，要么使用指定的唯一name（一个UUID）更新现有定义。

from azure.keyvault.administration import KeyVaultDataAction, KeyVaultPermission, KeyVaultRoleScope

role_name = "customRole"
scope = KeyVaultRoleScope.GLOBAL
permissions = [KeyVaultPermission(data_actions=[KeyVaultDataAction.CREATE_HSM_KEY])]
role_definition = client.set_role_definition(scope=scope, role_name=role_name, permissions=permissions)

new_permissions = [
    KeyVaultPermission(
        data_actions=[KeyVaultDataAction.READ_HSM_KEY],
        not_data_actions=[KeyVaultDataAction.CREATE_HSM_KEY]
    )
]
unique_definition_name = role_definition.name
updated_definition = client.set_role_definition(
    scope=scope, name=unique_definition_name, role_name=role_name, permissions=new_permissions
)

get_role_definition可以由KeyVaultAccessControlClient使用，以获取具有指定作用域和唯一名称的角色定义。

fetched_definition = client.get_role_definition(scope=scope, name=unique_definition_name)

delete_role_definition可以由KeyVaultAccessControlClient使用，以删除具有指定作用域和唯一名称的角色定义。

client.delete_role_definition(scope=scope, name=unique_definition_name)

列出所有角色分配

list_role_assignments可以由KeyVaultAccessControlClient使用，以列出所有当前角色分配。

from azure.keyvault.administration import KeyVaultRoleScope

role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)
for assignment in role_assignments:
    assert assignment.properties
    print(f"Role assignment name: {assignment.name}")
    print(f"Principal ID associated with this assignment: {assignment.properties.principal_id}")

创建、获取和删除角色分配

角色分配将角色分配给服务主体。这需要角色定义ID和服务主体对象ID。您可以使用从检索到的角色定义列表中获取的ID，以及从上述片段中检索到的分配的principal_id。将这些值以及作用域提供给KeyVaultAccessControlClient的create_role_assignment方法。

from azure.keyvault.administration import KeyVaultRoleScope

scope = KeyVaultRoleScope.GLOBAL
role_assignment = client.create_role_assignment(scope=scope, definition_id=definition_id, principal_id=principal_id)
print(f"Role assignment {role_assignment.name} created successfully.")

get_role_assignment可以由KeyVaultAccessControlClient使用，以获取具有指定作用域和唯一名称的现有角色分配。

fetched_assignment = client.get_role_assignment(scope=scope, name=role_assignment.name)
assert fetched_assignment.properties
print(f"Role assignment for principal {fetched_assignment.properties.principal_id} fetched successfully.")

delete_role_assignment可以由KeyVaultAccessControlClient使用，以删除具有指定作用域和唯一名称的角色分配。

client.delete_role_assignment(scope=scope, name=role_assignment.name)

执行完整密钥备份

可以使用KeyVaultBackupClient备份您的整个密钥集合。完整密钥备份的备份存储是使用共享访问签名（SAS）认证的blob存储容器。

有关使用azure-storage-blob从凭证文档创建SAS令牌的更多详细信息，请参阅库的凭证文档。或者，您可以在存储资源管理器中生成SAS令牌。

CONTAINER_URL = os.environ["CONTAINER_URL"]
SAS_TOKEN = os.environ["SAS_TOKEN"]

backup_result: KeyVaultBackupResult = client.begin_backup(CONTAINER_URL, sas_token=SAS_TOKEN).result()
print(f"Azure Storage Blob URL of the backup: {backup_result.folder_url}")

请注意，begin_backup方法返回一个轮询器。在轮询器上调用result()将返回一个包含备份信息的KeyVaultBackupResult。在轮询器上调用wait()将阻止操作完成，而不会返回对象。

执行完整密钥还原

可以使用 KeyVaultBackupClient 从备份中恢复您的整个密钥集合。完整密钥恢复的数据源是使用共享访问签名身份验证访问的存储blob。您还需要从上面的代码片段获取备份的URL（KeyVaultBackupResult.folder_url）。

有关使用azure-storage-blob从凭证文档创建SAS令牌的更多详细信息，请参阅库的凭证文档。或者，您可以在存储资源管理器中生成SAS令牌。

SAS_TOKEN = os.environ["SAS_TOKEN"]

# `backup_result` is the KeyVaultBackupResult returned by `begin_backup`
client.begin_restore(backup_result.folder_url, sas_token=SAS_TOKEN).wait()
print("Vault restored successfully.")

请注意，begin_restore 方法返回一个轮询器。与 begin_backup 返回的轮询器不同，此轮询器的 result 方法返回 None；因此，调用 wait() 在功能上相同。

执行选择密钥还原

要从已备份的保险库中恢复单个密钥而不是所有密钥，请在上述代码片段中显示的 begin_restore 方法中提供密钥名作为 key_name 参数。

故障排除

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

通用

密钥保管库客户端引发在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存储库中提供了一些示例。这些示例提供了Key Vault场景的示例代码。

• 创建/更新/删除角色定义和角色分配（异步版本）
• 完整备份和恢复（异步版本）
• 列出和更新密钥保管库设置（异步版本）

其他文档

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

有关托管HSM的更多详细文档，请参阅服务文档。

贡献

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

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

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

版本历史记录

4.4.0 (2024-02-22)

新增功能

• 添加了对服务API版本 7.5 的支持
• (从4.4.0b2开始) KeyVaultBackupClient.begin_backup 和 KeyVaultBackupClient.begin_restore 现在接受一个 use_managed_identity 关键字参数，以启用通过托管身份进行身份验证

错误修复

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

其他更改

• Python 3.7 已不再受支持。请使用 Python 版本 3.8 或更高版本。
• 密钥保管库 API 版本 7.5 现在是默认版本
• 已更新最小 azure-core 版本到 1.29.5
• 删除了 azure-common 的依赖

4.4.0b2 (2023-11-03)

新增功能

• 添加了对服务 API 版本 7.5-preview.1 的支持
• KeyVaultBackupClient.begin_backup 和 KeyVaultBackupClient.begin_restore 现在接受一个 use_managed_identity 关键字参数，以启用通过托管标识进行身份验证

其他更改

• 密钥保管库 API 版本 7.5-preview.1 现在是默认版本

4.4.0b1 (2023-05-16)

错误修复

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

4.3.0 (2023-03-16)

新增功能

• 添加了对服务 API 版本 7.4 的支持
• 每个客户端都有一个 send_request 方法，可用于使用客户端现有的管道发送自定义请求 (#25172)
• (从 4.3.0b1) 添加了同步和异步 KeyVaultSettingsClient 以获取和更新托管 HSM 设置
• KeyVaultSetting 类有一个 getboolean 方法，如果可能，将返回设置 value 的 bool 值，否则引发 ValueError

破坏性更改

这些更改不会影响稳定版本（如 4.2.0）的 API。只有针对类似 4.3.0b1 这样的 beta 版本编写的代码可能会受到影响。

• KeyVaultSettingsClient.update_setting 现在接受一个单独的 setting 参数（一个 KeyVaultSetting 实例），而不是 name 和 value
• KeyVaultSetting 模型的 type 参数和属性已被重命名为 setting_type
• SettingType 枚举已被重命名为 KeyVaultSettingType

其他更改

• 密钥保管库 API 版本 7.4 现在是默认版本
• (从 4.3.0b1) Python 3.6 已不再受支持。请使用 Python 版本 3.7 或更高版本。
• (从 4.3.0b1) 已更新最小 azure-core 版本到 1.24.0
• (从 4.3.0b1) 已删除 msrest 依赖
• (从 4.3.0b1) 已删除 six 依赖
• (从 4.3.0b1) 添加了对 isodate>=0.6.1 的依赖 (isodate 由 msrest 需要)
• (从 4.3.0b1) 添加了对 typing-extensions>=4.0.1 的依赖

4.3.0b1 (2022-11-15)

新增功能

• 添加了同步和异步 KeyVaultSettingsClient 以获取和更新托管 HSM 设置。
• 添加了对服务 API 版本 7.4-preview.1 的支持

其他更改

• Python 3.6 已不再受支持。请使用 Python 版本 3.7 或更高版本。
• 密钥保管库 API 版本 7.4-preview.1 现在是默认版本
• 已更新最小 azure-core 版本到 1.24.0
• 已删除 msrest 依赖
• 已删除 six 依赖
• 添加了对 isodate>=0.6.1 的依赖 (isodate 由 msrest 需要)
• 添加了对 typing-extensions>=4.0.1 的依赖

4.2.0 (2022-09-19)

破坏性更改

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

4.1.1 (2022-08-11)

其他更改

• 文档改进 (#25039)

4.1.0 (2022-03-28)

新增功能

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

其他更改

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

4.1.0b3（2022-02-08）

其他更改

• 不再支持Python 2.7。请使用Python版本3.6或更高版本。
• 已更新最低azure-core版本为1.20.0
• (从4.1.0b2开始)为了支持多租户身份验证，在挑战身份验证请求期间，现在get_token调用传入一个tenant_id关键字参数（#20698）

4.1.0b2（2021-11-11）

新增功能

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

其他更改

• 已更新最低azure-core版本为1.15.0

4.1.0b1（2021-09-09）

新增功能

• 密钥保管库API版本7.3-preview现在为默认版本

4.0.0 (2021-06-22)

变更

• 密钥保管库API版本7.2现在为默认版本
• KeyVaultAccessControlClient.delete_role_assignment和.delete_role_definition不再在要删除的资源未找到时引发错误
• 将最低azure-core版本提升到1.11.0

新增

• KeyVaultAccessControlClient.set_role_definition接受一个可选的仅关键字参数assignable_scopes

破坏性更改

• KeyVaultAccessControlClient.delete_role_assignment和.delete_role_definition返回None
• 在KeyVaultAccessControlClient.set_role_definition中更改了参数顺序。permissions现在是可选的仅关键字参数
• 将BackupOperation重命名为KeyVaultBackupResult，并删除了除其folder_url属性外的所有属性
• 删除了RestoreOperation和SelectiveKeyRestoreOperation类
• 删除了KeyVaultBackupClient.begin_selective_restore。要恢复单个密钥，请将密钥的名称传递给KeyVaultBackupClient.begin_restore

  # before (4.0.0b3):
  client.begin_selective_restore(folder_url, sas_token, key_name)
  
  # after:
  client.begin_restore(folder_url, sas_token, key_name=key_name)
  

• 删除了KeyVaultBackupClient.get_backup_status和.get_restore_status。使用由KeyVaultBackupClient.begin_backup和.begin_restore返回的轮询器来检查操作是否已完成
• KeyVaultRoleAssignment的principal_id、role_definition_id和scope现在是properties属性的一部分

  # before (4.0.0b3):
  print(KeyVaultRoleAssignment.scope)
  
  # after:
  print(KeyVaultRoleAssignment.properties.scope)
  

• 重命名了KeyVaultPermission属性
  • allowed_actions -> actions
  • denied_actions -> not_actions
  • allowed_data_actions -> data_actions
  • denied_data_actions -> denied_data_actions
• 在KeyVaultAccessControlClient.create_role_assignment、.delete_role_assignment和.get_role_assignment中将参数role_assignment_name重命名为name
• 在KeyVaultAccessControlClient.delete_role_definition和.get_role_definition中将参数role_definition_name重命名为name
• 在KeyVaultAccessControlClient方法中将参数role_scope重命名为scope

4.0.0b3（2021-02-09）

新增

• KeyVaultAccessControlClient支持管理自定义角色定义

破坏性更改

• 将KeyVaultBackupClient.begin_full_backup()重命名为.begin_backup()
• 将KeyVaultBackupClient.begin_full_restore()重命名为.begin_restore()
• 将BackupOperation.azure_storage_blob_container_uri重命名为.folder_url
• 将BackupOperation、RestoreOperation和SelectiveKeyRestoreOperation的id属性重命名为job_id
• 将KeyVaultBackupClient.begin_restore()和.begin_selective_restore()的blob_storage_uri参数重命名为folder_url
• 从KeyVaultBackupClient.begin_restore()和.begin_selective_restore()中删除了冗余的folder_name参数（folder_url参数包含文件夹名称）
• 重命名了KeyVaultPermission属性
  • actions -> allowed_actions
  • data_actions -> allowed_data_actions
  • not_actions -> denied_actions
  • not_data_actions -> denied_data_actions
• 将KeyVaultRoleAssignment.assignment_id重命名为.role_assignment_id
• 重命名了KeyVaultRoleScope枚举值
  • global_value -> GLOBAL
  • keys_value -> KEYS

4.0.0b2 (2020-10-06)

新增

• KeyVaultBackupClient.get_backup_status 和 .get_restore_status 通过作业ID启用检查待处理操作的状态（#13718）

破坏性更改

• KeyVaultAccessControlClient.create_role_assignment 的 role_assignment_name 参数现在是一个可选的关键字参数。当未传递此参数时，客户端将生成角色分配的名称。（#13512）

4.0.0b1 (2020-09-08)

新增

• KeyVaultAccessControlClient 执行基于角色的访问控制操作
• KeyVaultBackupClient 执行完整密钥库备份以及完整和选择性还原操作