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

[アーティクル]
04/03/2023

Azure Key Vault は、セキュリティで保護されたストレージと、クラウドアプリケーション全体で使用される証明書の自動管理を提供するクラウドサービスです。複数の証明書と同じ証明書の複数のバージョンを Azure Key Vaultに保持できます。コンテナー内の各証明書には、証明書の発行と有効期間を制御するポリシーと、有効期限近くの証明書として実行されるアクションが関連付けられています。

Azure Key Vault証明書クライアントライブラリを使用すると、証明書をプログラムで管理し、証明書、ポリシー、発行者、連絡先を作成、更新、一覧表示、削除する方法を提供できます。ライブラリでは、保留中の証明書操作の管理と削除された証明書の管理もサポートされています。

作業の開始

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

NuGet を使用して .NET 用の Azure Key Vault証明書クライアントライブラリをインストールします。

dotnet add package Azure.Security.KeyVault.Certificates

前提条件

Azure サブスクリプション。
既存の Azure Key Vault。 Azure Key Vaultを作成する必要がある場合は、Azure Portal または Azure CLI を使用できます。
RBAC (推奨) またはアクセス制御を使用した既存の Azure Key Vaultへの承認。

Azure CLI を使用する場合は、と <your-key-vault-name> を独自の一意の名前に置き換えます<your-resource-group-name>。

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

クライアントを認証する

Azure Key Vault サービスと対話するには、CertificateClient クラスのインスタンスを作成する必要があります。ポータルで "DNS 名" と表示される コンテナー URL と、クライアントオブジェクトをインスタンス化するための資格情報が必要です。

次に示す例では、を DefaultAzureCredential使用します。これは、ローカルの開発環境や運用環境を含むほとんどのシナリオに適しています。また、運用環境での認証にはマネージド ID を使用することをお勧めします。さまざまな認証方法とそれに対応する資格情報の種類の詳細については、 Azure ID のドキュメントを参照してください。

以下に DefaultAzureCredential 示すプロバイダー、または Azure SDK で提供されているその他の資格情報プロバイダーを使用するには、まず Azure.Identity パッケージをインストールする必要があります。

dotnet add package Azure.Identity

CertificateClient の作成

をインスタンス化 DefaultAzureCredential してクライアントに渡します。トークン資格情報の同じインスタンスは、同じ ID で認証する場合は、複数のクライアントで使用できます。

// Create a new certificate client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

主要な概念

KeyVaultCertificate

KeyVaultCertificateは、Azure Key Vault内の基本的なリソースです。証明書を使用して、暗号化または署名されたデータの暗号化と検証を行います。

CertificateClient

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

スレッドセーフ

すべてのクライアントインスタンスメソッドがスレッドセーフであり、相互に独立していることを保証します (ガイドライン)。これにより、スレッド間であっても、クライアントインスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

例

Azure.Security.KeyVault.Certificates パッケージでは、同期 API と非同期 API がサポートされています。

次のセクションでは、上記で作成したをclient使用したいくつかのコードスニペットについて説明します。Azure Key Vault 証明書サービス関連の最も一般的なタスクの一部を説明します。

非同期の例

証明書を非同期的に作成する
証明書を非同期的に一覧表示する
証明書を非同期的に削除する

証明書を作成する

StartCreateCertificateは、Azure Key Vaultに格納される証明書を作成します。同じ名前の証明書が既に存在する場合は、新しいバージョンの証明書が作成されます。証明書を作成するときに、ユーザーは証明書の有効期間を制御するポリシーを指定できます。ポリシーが指定されていない場合は、既定のポリシーが使用されます。操作は StartCreateCertificate を CertificateOperation返します。次の例では、既定のポリシーを使用して自己署名証明書を作成します。

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

注: 証明書の発行者と検証方法によっては、証明書の作成と署名に不確定な時間がかかる場合があります。ユーザーは、自己署名証明書や既知の応答時間を持つ発行者など、アプリケーションのスコープで操作を合理的に完了できる場合にのみ、証明書操作を待機する必要があります。

証明書の取得

GetCertificateは、Azure Key Vault に格納されている証明書の最新バージョンとそのを取得しますCertificatePolicy。

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion は、コンテナー内の証明書の特定のバージョンを取得します。

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

既存の証明書を更新する

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

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

証明書の一覧の取得

GetCertificates はコンテナー内の証明書を列挙し、証明書の選択プロパティを返します。証明書の機密フィールドは返されません。この操作には、証明書/リストのアクセス許可が必要です。

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

証明書の削除

DeleteCertificateは、Azure Key Vaultに格納されている証明書のすべてのバージョンを削除します。 Azure Key Vaultで論理的な削除が有効になっていない場合、この操作によって証明書が完全に削除されます。論理的な削除が有効になっている場合、証明書は削除対象としてマークされ、必要に応じて、スケジュールされた消去日まで消去または回復できます。

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

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

非同期 API は、同期に対応する API と同じですが、非同期メソッドの一般的な "Async" サフィックスを使用してを返し、を Task返します。

この例では、指定した省略可能な引数を使用して、Azure Key Vaultに証明書を作成します。

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

証明書を非同期的に一覧表示する

証明書の一覧表示はメソッドのGetPropertiesOfCertificatesAsync待機に依存しませんが、ステートメントで使用できるをawait foreach返AsyncPageable<CertificateProperties>します。

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

証明書を非同期的に削除する

証明書を消去する前に非同期的に削除する場合は、操作でメソッドを WaitForCompletionAsync 待機できます。既定では、このループは無期限にループしますが、を渡 CancellationTokenすことで取り消すことができます。

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
await operation.WaitForCompletionAsync();

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.Name);

トラブルシューティング

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

全般

.NET SDK を使用して Azure Key Vault証明書クライアントライブラリを操作すると、サービスによって返されるエラーは、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。

たとえば、Azure Key Vaultに存在しないキーを取得しようとすると、 404 を示すNot Foundエラーが返されます。

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

操作のクライアント要求 ID など、追加情報がログに記録されていることがわかります。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"CertificateNotFound","message":"Certificate not found: MyCertificate"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

次のステップ

この GitHub リポジトリでは、いくつかの Azure Key Vault 証明書クライアントライブラリサンプルを使用できます。これらのサンプルでは、Azure Key Vaultの操作中に一般的に発生するその他のシナリオのコード例を示します。

Sample1_HelloWorld.md - 次を含む Azure Key Vault証明書を操作する場合:
- 証明書を作成する
- 既存の証明書を取得する
- 既存の証明書を更新する
- 証明書の削除
Sample2_GetCertificates.md - Azure Key Vault証明書を操作するためのコード例を次に示します。
- 証明書の作成
- Key Vault内のすべての証明書を一覧表示する
- 指定した証明書のバージョンを一覧表示する
- Key Vaultから証明書を削除する
- 削除された証明書をKey Vaultに一覧表示する

その他のドキュメント

Azure Key Vaultの詳細なドキュメントについては、API リファレンスドキュメントを参照してください。
Secrets クライアントライブラリについては、「 Secrets クライアントライブラリ」を参照してください。
Keys クライアントライブラリについては、「 Keys クライアントライブラリ」を参照してください。

共同作成

これらのライブラリの構築、テスト、および貢献の詳細については、 CONTRIBUTING.md を参照してください。

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

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

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

インプレッション数

次の方法で共有

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

作業の開始

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

前提条件

クライアントを認証する

CertificateClient の作成

主要な概念

KeyVaultCertificate

CertificateClient

スレッドセーフ

その他の概念

例

同期の例

非同期の例

証明書を作成する

証明書の取得

既存の証明書を更新する

証明書の一覧の取得

証明書の削除

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

証明書を非同期的に一覧表示する

証明書を非同期的に削除する

トラブルシューティング

全般

次のステップ

その他のドキュメント

共同作成

その他のリソース

次の方法で共有

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

作業の開始

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

前提条件

クライアントを認証する

CertificateClient の作成

主要な概念

KeyVaultCertificate

CertificateClient

スレッド セーフ

その他の概念

例

同期の例

非同期の例

証明書を作成する

証明書の取得

既存の証明書を更新する

証明書の一覧の取得

証明書の削除

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

証明書を非同期的に一覧表示する

証明書を非同期的に削除する

トラブルシューティング

全般

次のステップ

その他のドキュメント

共同作成

その他のリソース

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

スレッドセーフ