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

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

Azure Key Vault は、パスワードやデータベース接続文字列などのシークレットのセキュリティで保護されたストレージを提供するクラウドサービスです。

Azure Key Vault シークレットクライアントライブラリを使用すると、トークン、パスワード、API キー、その他のシークレットへのアクセスを安全に格納および制御できます。このライブラリには、シークレットとそのバージョンを作成、取得、更新、削除、消去、バックアップ、復元、一覧表示する操作が用意されています。

作業の開始

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

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

dotnet add package Azure.Security.KeyVault.Secrets

前提条件

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

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

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

dotnet add package Azure.Identity

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

// Create a new secret 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 SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

主要な概念

KeyVaultSecret

はKeyVaultSecret、Azure Key Vault内の基本的なリソースです。開発者の観点から、Azure Key Vault API はシークレット値を文字列として受け入れて返します。

SecretClient

では SecretClient 、SDK で同期操作と非同期操作の両方が提供されるため、アプリケーションのユースケースに基づいてクライアントを選択できます。を初期化SecretClientしたら、Azure Key Vault内のシークレットと対話できます。

スレッドセーフ

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

その他の概念

例

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

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

非同期の例

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

シークレットの作成

SetSecretは、KeyVaultSecretAzure Key Vaultに格納されるを作成します。同じ名前のシークレットが既に存在する場合は、新しいバージョンのシークレットが作成されます。

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

シークレットを取得する

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

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

既存のシークレットを更新する

UpdateSecretPropertiesは、以前に Azure Key Vaultに格納されているシークレットを更新します。シークレットの属性のみが更新されます。値を更新するには、同じ名前のシークレットでを呼び出 SecretClient.SetSecret します。

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

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

StartDeleteSecretは、Azure Key Vaultに以前に格納されているシークレットを削除する実行時間の長い操作を開始します。操作が完了するのを待たずに、シークレットをすぐに取得できます。 Azure Key Vaultで論理的な削除が有効になっていない場合、この操作によってシークレットが完全に削除されます。

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

シークレットを削除して消去する

シークレットの消去または回復を試みる前に、実行時間の長い操作が完了するまで待つ必要があります。これを行うには、次に示すようにループでを呼び出 UpdateStatus します。

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

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

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

シークレットのリスト

この例では、指定した Azure Key Vault内のすべてのシークレットを一覧表示します。すべてのシークレットを一覧表示する場合、値は返されません。値を取得するには、を呼び出 SecretClient.GetSecret す必要があります。

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

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

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

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

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

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

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

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

シークレットを非同期的に削除する

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

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

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

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

トラブルシューティング

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

全般

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

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

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

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

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

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_BackupAndRestore.md - Azure Key Vault シークレットを操作する次のコードスニペットが含まれています。
- シークレットのバックアップと回復
Sample3_GetSecrets.md - Azure Key Vault シークレットを操作するためのコード例。
- シークレットを作成する
- Key Vault内のすべてのシークレットを一覧表示する
- Key Vaultのシークレットを更新する
- 指定したシークレットのバージョンを一覧表示する
- Key Vaultからシークレットを削除する
- 削除されたシークレットをKey Vaultに一覧表示する

その他のドキュメント

Azure Key Vaultの詳細なドキュメントについては、API リファレンスドキュメントを参照してください。
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.0

作業の開始

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

前提条件

クライアントを認証する

主要な概念

KeyVaultSecret

SecretClient

スレッドセーフ

その他の概念

例

同期の例

非同期の例

シークレットの作成

シークレットを取得する

既存のシークレットを更新する

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

シークレットを削除して消去する

シークレットのリスト

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

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

シークレットを非同期的に削除する

トラブルシューティング

全般

次の手順

その他のドキュメント

共同作成

その他のリソース

次の方法で共有

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

作業の開始

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

前提条件

クライアントを認証する

主要な概念

KeyVaultSecret

SecretClient

スレッド セーフ

その他の概念

例

同期の例

非同期の例

シークレットの作成

シークレットを取得する

既存のシークレットを更新する

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

シークレットを削除して消去する

シークレットのリスト

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

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

シークレットを非同期的に削除する

トラブルシューティング

全般

次の手順

その他のドキュメント

共同作成

その他のリソース

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

スレッドセーフ