Python 用 Azure Key Vault 管理クライアント ライブラリ - バージョン 4.3.0

作業の開始

パッケージをインストールする

pip を使用して azure-keyvault-administration と azure-identity をインストールします。

pip install azure-keyvault-administration azure-identity

azure-identity は、次に示すように、Azure Active Directory 認証に使用されます。

前提条件

• Azure サブスクリプション
• Python 3.7 以降
• 既存の Key Vault Managed HSM。 作成する必要がある場合は、 このドキュメントの手順に従って Azure CLI を使用して作成できます。

クライアントを認証する

Azure Key Vault サービスと対話するには、KeyVaultAccessControlClient または KeyVaultBackupClient のいずれかのインスタンスと、コンテナー URL (Azure Portal では "DNS 名" と表示される場合があります) と資格情報オブジェクトが必要です。 このドキュメントでは、ローカルの開発環境や運用環境など、ほとんどのシナリオ に適した DefaultAzureCredential の使用について説明します。 運用環境での認証には マネージド ID を 使用することをお勧めします。

その他の認証方法とそれに対応する資格情報の種類の詳細については、 azure-identity のドキュメントを参照してください。

KeyVaultAccessControlClient を作成する

適切な認証方法を使用するように DefaultAzureCredential 用に環境を構成した後、次の操作を行ってアクセス制御クライアントを作成できます (の vault_url 値を Managed 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
)

メモ：非同期クライアントの場合は、代わりに をKeyVaultAccessControlClientインポートazure.keyvault.administration.aioします。

KeyVaultBackupClient を作成する

適切な認証方法を使用するように DefaultAzureCredential 用に環境を構成した後、次の操作を行ってバックアップ クライアントを作成できます (の vault_url 値を Managed 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
)

メモ：非同期クライアントの場合は、代わりに をKeyVaultBackupClientインポートazure.keyvault.administration.aioします。

KeyVaultSettingsClient を作成する

適切な認証方法を使用するように DefaultAzureCredential 用に環境を構成した後、次の操作を行って設定クライアントを作成できます (の vault_url 値を Managed 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
)

メモ：非同期クライアントの場合は、代わりに をKeyVaultSettingsClientインポートazure.keyvault.administration.aioします。

主要な概念

ロール定義

ロール定義は、読み取り、書き込み、削除など、実行できる操作を定義します。 また、許可された操作から除外される操作を定義することもできます。

ロール定義は、ロールの割り当ての一部として指定されます。

ロール割り当て

ロールの割り当ては、サービス プリンシパルへのロール定義の関連付けです。 これらは、作成、一覧表示、個別にフェッチ、および削除できます。

KeyVaultAccessControlClient

は KeyVaultAccessControlClient 、ロールの定義とロールの割り当てを管理します。

KeyVaultBackupClient

では KeyVaultBackupClient 、完全キー バックアップ、完全キー復元、選択的キー復元が実行されます。

KeyVaultSettingsClient

は KeyVaultSettingsClient 、Managed 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)

キーの完全バックアップを実行する

キーのコレクション全体をバックアップします。 完全キー バックアップのバッキング ストアは、Shared Access Signature 認証を使用する BLOB ストレージ コンテナーです。

を使用した BlobServiceClientSAS トークンの作成の詳細については、 こちらのサンプルを参照してください。 または、Storage Explorerで 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)

完全キーの復元を実行する

バックアップからキーのコレクション全体を復元します。 完全キー復元のデータ ソースは、Shared Access Signature 認証を使用してアクセスされるストレージ BLOB です。 また、上記のスニペットの もazure_storage_blob_container_uri必要です。

を使用した BlobServiceClientSAS トークンの作成の詳細については、 こちらのサンプルを参照してください。 または、Storage Explorerで 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診断する方法の詳細については、トラブルシューティング ガイドを参照してください。

全般

Key Vaultクライアントは、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 に対する操作の実行にのみ使用できるため、Key Vaultで実行しようとするとエラーが発生します。

次のステップ

Azure SDK for Python GitHub リポジトリでは、いくつかのサンプルを入手できます。 これらのサンプルでは、追加のKey Vaultシナリオのコード例を示します。 |ファイル |説明 | |-------------|-------------| |access_control_operations.py |ロール定義とロールの割り当ての作成/更新/削除 | |access_control_operations_async.py |非同期クライアントを使用したロール定義とロールの割り当ての作成/更新/削除 | |backup_restore_operations.py |完全バックアップと復元 | |backup_restore_operations_async.py |非同期クライアントを使用した完全バックアップと復元 | |settings_operations.py |Key Vault設定の一覧表示と更新 | |settings_operations_async.py |非同期クライアントを使用してKey Vault設定を一覧表示および更新する |

その他のドキュメント

Azure Key Vaultに関するより広範なドキュメントについては、API リファレンス ドキュメントを参照してください。

Managed HSM に関するより広範なドキュメントについては、 サービスのドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトは、「Microsoft のオープン ソースの倫理規定」を採用しています。 詳細については、倫理規定についてよくあるご質問を参照するか、opencode@microsoft.com 宛てにご質問またはコメントをお送りください。