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 宛てにご質問またはコメントをお送りください。