Python 用 Azure Key Vault Keys クライアント ライブラリ - バージョン 4.8.0
Azure Key Vault は、次の問題の解決に役立ちます。
- 暗号化キー管理 (このライブラリ) - データの暗号化に使用されるキーへのアクセスの作成、格納、制御
- シークレット管理 (azure-keyvault-secrets) - トークン、パスワード、証明書、API キー、およびその他のシークレットへのアクセスを安全に格納および制御する
- 証明書管理 (azure-keyvault-certificates) - パブリックおよびプライベート SSL/TLS 証明書の作成、管理、デプロイ
- コンテナーの管理 (azure-keyvault-administration) - ロールベースのアクセス制御 (RBAC)、およびコンテナー レベルのバックアップと復元のオプション
ソースコード | パッケージ (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-keys と azure-identity をインストールします。
pip install azure-keyvault-keys azure-identity
azure-identity は、次に示すように、Azure Active Directory 認証に使用されます。
前提条件
- Azure サブスクリプション
- Python 3.7 以降
- 既存の Azure Key Vault。 作成する必要がある場合は、 このドキュメントの手順に従って Azure CLI を使用して作成できます。
- Managed HSM を使用している場合は、既存の Key Vault Managed HSM。 Managed HSM を作成する必要がある場合は、 このドキュメントの手順に従って Azure CLI を使用して作成できます。
クライアントを認証する
Azure Key Vault サービスと対話するには、KeyClient のインスタンスと、コンテナーの URL と資格情報オブジェクトが必要です。 このドキュメントでは、 DefaultAzureCredential の使用を示します。これは、ローカルの開発環境や運用環境など、ほとんどのシナリオに適しています。 運用環境では、認証に マネージド ID を 使用することをお勧めします。
その他の認証方法と、それに対応する資格情報の種類の詳細については、 azure-identity のドキュメントを参照してください。
クライアントの作成
適切な認証方法を使用するように DefaultAzureCredential 用に環境を構成した後、次の操作を実行してキー クライアントを作成できます (の VAULT_URL 値をコンテナーの URL に置き換えます)。
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)
メモ：非同期クライアントの場合は、代わりに を
KeyClientインポートazure.keyvault.keys.aioします。
主要な概念
キー
Azure Key Vaultでは、RSA キーと楕円曲線キーを作成して格納できます。 必要に応じて、両方をハードウェア セキュリティ モジュール (HSM) で保護できます。 Azure Key Vaultでは、それらの操作を使用して暗号化操作を実行することもできます。 キーとサポートされている操作とアルゴリズムの詳細については、Key Vaultドキュメントを参照してください。
KeyClient では、次の 例 に示すように、コンテナーにキーを作成し、コンテナーから既存のキーを取得し、キー メタデータを更新し、キーを削除できます。
例
このセクションには、一般的なタスクをカバーするコード スニペットが含まれています。
- キーを作成します
- キーの取得
- 既存のキーを更新する
- キーを削除します
- キーの自動ローテーションを構成する
- キーのリスト
- 暗号化操作を実行する
- 非同期 API
- キーを非同期に作成する
- キーを非同期的に一覧表示する
キーの作成
create_rsa_key と create_ec_key 、それぞれ RSA キーと楕円曲線キーをコンテナーに作成します。 同じ名前のキーが既に存在する場合は、そのキーの新しいバージョンが作成されます。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)
# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)
キーの取得
get_key は、以前にコンテナーに格納されていたキーを取得します。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)
既存のキーを更新する
update_key_propertiesは、以前にKey Vaultに格納されているキーのプロパティを更新します。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)
print(updated_key.name)
print(updated_key.properties.enabled)
キーの削除
begin_delete_key要求Key Vaultキーを削除し、削除が完了するまで待機できるポーリングャーを返します。 待機は、コンテナーで 論理的な削除 が有効になっており、できるだけ早くキーを消去 (完全に削除) する場合に役立ちます。 論理的な削除が無効になっている場合、begin_delete_keyそれ自体は永続的です。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()
print(deleted_key.name)
print(deleted_key.deleted_date)
キーの自動ローテーションを構成する
update_key_rotation_policy では、ローテーション ポリシーを指定することで、キーの自動キーローテーションを構成できます。 さらに、 rotate_key では、指定されたキーの新しいバージョンを作成することで、キーをオンデマンドでローテーションできます。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)
# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")
# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")
キーのリスト
list_properties_of_keys は、クライアントのコンテナー内のすべてのキーのプロパティを一覧表示します。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()
for key in keys:
# the list doesn't include values or versions of the keys
print(key.name)
暗号化操作
CryptographyClient は、特定のキーを使用して暗号化操作 (暗号化/暗号化解除、ラップ/ラップ解除、署名/検証) を有効にします。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"
result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)
暗号化 API の詳細については、 パッケージのドキュメントを参照 してください。
非同期 API
このライブラリには、非同期 API の完全なセットが含まれています。 これらを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメント を参照してください。
非同期クライアントと資格情報は、不要になったら閉じる必要があります。 これらのオブジェクトは非同期コンテキスト マネージャーであり、非同期 close メソッドを定義します。 次に例を示します。
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()
# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
キーを非同期に作成する
create_rsa_key と create_ec_key 、それぞれ RSA キーと楕円曲線キーをコンテナーに作成します。 同じ名前のキーが既に存在する場合は、新しいバージョンのキーが作成されます。
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)
# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)
キーを非同期的に一覧表示する
list_properties_of_keys は、クライアントのコンテナー内のすべてのキーのプロパティを一覧表示します。
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()
async for key in keys:
print(key.name)
トラブルシューティング
さまざまな障害シナリオをazure-keyvault-keys診断する方法の詳細については、トラブルシューティング ガイドを参照してください。
全般
Key Vaultクライアントは、azure-core で定義されている例外を発生させます。 たとえば、コンテナーに存在しないキーを取得しようとすると、 KeyClient によって ResourceNotFoundError が発生します。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
key_client.get_key("which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
ログの記録
このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッションに関する基本情報 (URL、ヘッダーなど) は INFO レベルでログに記録されます。
要求/応答本文、未変換ヘッダーなど、詳細な DEBUG レベルのログは、 引数を使用してクライアントで logging_enable 有効にすることができます。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
import sys
import logging
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential, logging_enable=True)
同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。
client.get_key("my-key", logging_enable=True)
次のステップ
いくつかのサンプルは、Azure SDK for Python GitHub リポジトリで入手できます。
追加のKey Vaultシナリオのコード例を次に示します。 |ファイル |説明 | |-------------|-------------| |hello_world.py (非同期バージョン) |キーの作成/取得/更新/削除 | |list_operations.py (非同期バージョン) |キーの基本的なリスト操作 | |backup_restore_operations.py (非同期バージョン) |キーのバックアップと回復 | |recover_purge_operations.py (非同期バージョン) |キーの回復と消去 | |send_request.py |クライアント メソッドを使用する send_request |
その他のドキュメント
Azure Key Vaultの詳細なドキュメントについては、API リファレンス ドキュメントを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトは、「Microsoft のオープン ソースの倫理規定」を採用しています。 詳細については、倫理規定についてよくあるご質問を参照するか、opencode@microsoft.com 宛てにご質問またはコメントをお送りください。
Azure SDK for Python