Python 用 Azure Key Vault 証明書クライアント ライブラリ - バージョン 4.7.0

作業の開始

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

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

pip install azure-keyvault-certificates azure-identity

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

前提条件

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

クライアントを認証する

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

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

クライアントの作成

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

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

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

主要な概念

CertificateClient

CertificateClient を使用すると、コンテナーから証明書を取得し、新しい証明書と既存の証明書の新しいバージョンを作成し、証明書メタデータを更新し、証明書を削除できます。 証明書の発行者、連絡先、および管理ポリシーを管理することもできます。 これは、次の例で示 されています 。

例

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

• 証明書を作成します
• 証明書の取得
• 既存の証明書のプロパティを更新する
• 証明書を削除します
• 証明書のプロパティを一覧表示する
• 非同期操作
• 証明書を非同期に作成する
• 証明書のプロパティを非同期的に一覧表示する

証明書を作成する

begin_create_certificateは、Azure Key Vaultに格納する証明書を作成します。 同じ名前の証明書が既に存在する場合は、新しいバージョンの証明書が作成されます。 証明書を作成する前に、証明書の管理ポリシーを作成するか、既定のポリシーを使用します。 このメソッドは、実行時間の長い操作ポーリングャーを返します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

証明書の作成の状態を確認する場合は、投票者で を呼び出 status() すか、証明書の名前で get_certificate_operation できます。

証明書の取得

get_certificateは、以前にKey Vaultに格納されている証明書の最新バージョンを取得します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version は、証明書の特定のバージョンを取得します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

既存の証明書のプロパティを更新する

update_certificate_propertiesは、以前にKey Vaultに格納されている証明書を更新します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

証明書の削除

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

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

証明書のプロパティを一覧表示する

list_properties_of_certificatesは、指定したKey Vault内のすべての証明書のプロパティを一覧表示します。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

非同期操作

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

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

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

証明書を非同期に作成する

create_certificateは、Azure Key Vaultに格納される証明書を作成します。 同じ名前の証明書が既に存在する場合は、新しいバージョンの証明書が作成されます。 証明書を作成する前に、証明書の管理ポリシーを作成するか、既定のポリシーを使用します。 create_certificate作成が成功した場合は作成された証明書が返され、作成されていない場合は CertificateOperation が返されます。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

証明書のプロパティを非同期的に一覧表示する

list_properties_of_certificates は、クライアントのコンテナー内の証明書のすべてのプロパティを一覧表示します。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

トラブルシューティング

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

全般

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

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

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

try:
    certificate_client.get_certificate("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.certificates import CertificateClient
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 = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

ネットワーク トレース ログは、任意の 1 つの操作に対して有効にすることもできます。

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

次のステップ

Azure SDK for Python GitHub リポジトリでは、いくつかのサンプルを入手できます。 これらのサンプルでは、追加のKey Vaultシナリオのコード例を示します。 |ファイル |説明 | |-------------|-------------| |hello_world.py (非同期バージョン) |証明書の作成/取得/更新/削除 | |backup_restore_operations.py (非同期バージョン) |証明書のバックアップと回復 | |import_certificate.py (非同期バージョン) |PKCS#12 (PFX) と PEM 形式の証明書を Key Vault にインポートする | |list_operations.py (非同期バージョン) |証明書の一覧表示 | |recover_purge_operations.py (非同期バージョン) |証明書の回復と消去 | |issuers.py (非同期バージョン) |証明書発行者の管理 | |contacts.py (非同期バージョン) |証明書の連絡先を管理する | |parse_certificate.py (非同期バージョン) |証明書の秘密キーを抽出する |

その他のドキュメント

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

共同作成

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

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

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