Python 用 Azure Key Vault シークレット クライアント ライブラリ - バージョン 4.7.0

Azure Key Vault は、次の問題の解決に役立ちます。

• シークレット管理 (このライブラリ) - トークン、パスワード、証明書、API キー、その他のシークレットへのアクセスを安全に格納および制御します
• 暗号化キー管理 (azure-keyvault-keys) - データの暗号化に使用されるキーの作成、格納、およびアクセスの制御
• 証明書管理 (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-secrets と azure-identity をインストールします。

pip install azure-keyvault-secrets azure-identity

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

前提条件

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

クライアントを認証する

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

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

クライアントの作成

適切な認証方法を使用するように DefaultAzureCredential 用に環境を構成した後、次の操作を行ってシークレット クライアントを作成できます (の VAULT_URL 値をコンテナーの URL に置き換えます)。

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)

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

主要な概念

Secret

シークレットは、シークレット値とそれに関連付けられているメタデータと管理情報で構成されます。 このライブラリはシークレット値を文字列として処理しますが、Azure Key Vaultではそのような値は格納されません。 シークレットの詳細と、シークレットKey Vault格納および管理する方法については、Key Vaultドキュメントを参照してください。

SecretClient では、次の例に示すように、コンテナー内のシークレット値の設定、シークレット メタデータの更新、シークレットの削除 を行 うことができます。

例

このセクションには、一般的なタスクをカバーするコード スニペットが含まれています。

• シークレットを設定する
• シークレットを取得する
• シークレット メタデータを更新する
• シークレットを削除します
• シークレットを一覧表示する
• 非同期 API
• シークレットを非同期に作成する
• シークレットを非同期的に一覧表示する

シークレットを設定する

set_secret は、新しいシークレットを作成し、既存のシークレットの値を変更します。 指定した名前のシークレットが存在しない場合は、 set_secret その名前と指定された値を持つ新しいシークレットを作成します。 指定した名前が使用されている場合は、 set_secret 指定された値を使用して、そのシークレットの新しいバージョンを作成します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

シークレットを取得する

get_secretは、以前にKey Vaultに格納されているシークレットを取得します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")

print(secret.name)
print(secret.value)

シークレット メタデータを更新する

update_secret_properties はシークレットのメタデータを更新します。 シークレットの値を変更することはできません。 set_secret を使用してシークレットの値を設定します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"

# We will also disable the secret for further use

updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)

print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)

シークレットを削除します

begin_delete_secret要求Key Vaultシークレットを削除し、削除が完了するまで待機できるポーリングャーを返します。 待機は、コンテナーで 論理的な削除 が有効になっており、シークレットをできるだけ早く消去 (完全に削除) する場合に役立ちます。 論理的な削除が無効になっている場合、begin_delete_secretそれ自体は永続的です。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

シークレットのリスト

list_properties_of_secrets は、クライアントのコンテナー内のすべてのシークレットのプロパティを一覧表示します。 この一覧には、シークレットの値は含まれません。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

非同期 API

このライブラリには、非同期 API の完全なセットが含まれています。 それらを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメント を参照してください。

非同期クライアントと資格情報は、不要になったら閉じる必要があります。 これらのオブジェクトは非同期コンテキスト マネージャーであり、非同期 close メソッドを定義します。 次に例を示します。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = SecretClient(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 = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

シークレットを非同期に作成する

set_secretは、指定した省略可能な引数を使用して、Key Vaultにシークレットを作成します。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

secret = await secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

シークレットを非同期的に一覧表示する

list_properties_of_secrets は、クライアントのコンテナー内のすべてのシークレットのプロパティを一覧表示します。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

async for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

トラブルシューティング

さまざまな障害シナリオをazure-keyvault-secrets診断する方法の詳細については、トラブルシューティング ガイドを参照してください。

全般

Key Vaultクライアントは、azure-core で定義されている例外を発生させます。 たとえば、コンテナーに存在しないキーを取得しようとすると、 SecretClient によって ResourceNotFoundError が発生します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    secret_client.get_secret("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.secrets import SecretClient
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
secret_client = SecretClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。

secret_client.get_secret("my-secret", logging_enable=True)

次のステップ

Azure SDK for Python GitHub リポジトリでは、いくつかのサンプルを入手できます。 追加のKey Vaultシナリオのコード例を次に示します。 |ファイル |説明 | |-------------|-------------| |hello_world.py (非同期バージョン) |シークレットの作成/取得/更新/削除 | |list_operations.py (非同期バージョン) |シークレットの基本的なリスト操作 | |backup_restore_operations.py (非同期バージョン) |シークレットのバックアップと復元 | |recover_purge_operations.py (非同期バージョン) |シークレットの回復と消去 |

その他のドキュメント

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

共同作成

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

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

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