適用于 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 或更新版本才能使用此套件。如需詳細資訊，請參閱適用于 Python 的 Azure SDK 版本支援原則。

開始使用

安裝套件

使用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的實例，以及您在 Azure 入口網站) 和認證物件中看到的保存庫 URL (。 本檔示範如何使用 DefaultAzureCredential，這適用于大部分案例，包括本機開發和生產環境。 建議您在生產環境中使用 受控識別 進行驗證。

如需其他驗證方法及其對應認證類型的詳細資訊，請參閱 azure 身分識別 檔。

建立 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.aioKeyVaultAccessControlClient 入 。

建立 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.aioKeyVaultBackupClient 入 。

建立 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.aioKeyVaultSettingsClient 入 。

重要概念

角色定義

角色定義會定義可執行檔作業，例如讀取、寫入和刪除。 它也可以定義從允許的作業中排除的作業。

角色定義會指定為角色指派的一部分。

角色指派

角色指派是角色定義與服務主體的關聯。 您可以個別建立、列出、擷取和刪除它們。

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)

建立、取得和刪除角色指派

將角色指派給服務主體。 這需要角色定義識別碼和服務主體物件識別碼。 您可以從前者的角色定義擷取清單中使用識別碼，並從上述程式碼片段中擷取的清單中，為後者擷取指派 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 權杖的詳細資訊，請參閱 這裡的範例。 或者，您也可以在 儲存體總管 中產生 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 權杖的詳細資訊，請參閱 這裡的範例。 或者，您也可以在 儲存體總管 中產生 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 核心中定義的例外狀況。 例如，如果您嘗試取得不存在的角色指派，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 Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡 opencode@microsoft.com。