適用于 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.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)
建立、取得和刪除角色指派
將角色指派給服務主體。 這需要角色定義識別碼和服務主體物件識別碼。 您可以從前者的角色定義擷取清單中使用識別碼,並從上述程式碼片段中擷取的清單中,為後者擷取指派 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。