.NET 用 Azure KeyVault 管理クライアント ライブラリ - バージョン 4.3.0

  • [アーティクル]

Azure Key Vault Managed HSM は、FIPS 140-2 レベル 3 の検証済み HSM を使用してクラウド アプリケーションの暗号化キーを保護できるようにする、フル マネージドの高可用性シングルテナント標準準拠クラウド サービスです。

Azure Key Vault 管理ライブラリ クライアントは、完全バックアップ/復元、キー レベルのロールベースのアクセス制御 (RBAC) などの管理タスクをサポートします。

ソースコード | パッケージ (NuGet) | 製品ドキュメント | サンプル

作業の開始

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

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

dotnet add package Azure.Security.KeyVault.Administration

前提条件

Managed HSM リソースを作成するには、次の CLI コマンドを実行します。

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

取得 <your-user-object-id> するには、次の CLI コマンドを実行します。

az ad user show --id <your-user-principal> --query id

クライアントを認証する

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

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

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

dotnet add package Azure.Identity

マネージド HSM をアクティブにする

HSM をアクティブにするまでは、データ プレーンのコマンドはすべて無効です。 キーを作成することはできず、ロールを割り当てることもできません。 HSM をアクティブにできるのは、create コマンドの実行時に割り当てられた指定された管理者だけです。 HSM をアクティブにするには、セキュリティ ドメインをダウンロードする必要があります。

HSM をアクティブにするための要件は次のとおりです。

  • 少なくとも 3 つの RSA キー ペア (最大 10)
  • セキュリティ ドメイン (クォーラム) の暗号化を解除するために必要なキーの最小数を指定します

HSM をアクティブにするには、少なくとも 3 つ (最大 10 個) の RSA 公開キーを HSM に送信する必要があります。 HSM は、それらのキーでセキュリティ ドメインを暗号化して返します。 このセキュリティ ドメインが正常にダウンロードされると、HSM を使用する準備が整います。 加えて、クォーラムの指定も必要となります。クォーラムは、セキュリティ ドメインの暗号化を解除するために必要な秘密キーの最小数です。

次の例は、openssl を使用して 3 つの自己署名証明書を生成する方法を示しています。

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

セキュリティ ドメインをダウンロードして、マネージド HSM をアクティブにするには、az keyvault security-domain download コマンドを使用します。 次の例では、3 つの RSA キー ペアを使用し (このコマンドには公開キーのみが必要です)、クォーラムを 2 に設定します。

az keyvault security-domain download --hsm-name <your-managed-hsm-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

マネージド HSM へのアクセスの制御

作成時に割り当てられた指定された管理者は、"Managed HSM Administrators" 組み込みロールに自動的に追加されます。このロールは、他の制限付きアクセス許可の中でも、セキュリティ ドメインをダウンロードし、 データ プレーンアクセスのロールを管理できます。

キーに対して他のアクションを実行するには、"Managed HSM Crypto User" などの他のロールにプリンシパルを割り当てる必要があります。これにより、非破壊的キー操作を実行できます。

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

マネージド HSM を適切にセキュリティで保護するための ベスト プラクティス をお読みください。

KeyVaultAccessControlClient を作成する

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

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

KeyVaultBackupClient を作成する

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

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

KeyVaultSettingClient を作成する

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

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

主要な概念

KeyVaultRoleDefinition

KeyVaultRoleDefinitionは、アクセス許可のコレクションです。 ロール定義は、読み取り、書き込み、削除など、実行できる操作を定義します。 また、許可された操作から除外される操作を定義することもできます。

KeyVaultRoleDefinitions は、 の KeyVaultRoleAssignment一部として一覧表示および指定できます。

KeyVaultRoleAssignment

は KeyVaultRoleAssignment 、KeyVaultRoleDefinition とサービス プリンシパルの関連付けです。 これらは、作成、一覧表示、個別にフェッチ、および削除できます。

KeyVaultAccessControlClient

はKeyVaultAccessControlClient、同期操作と非同期操作の両方を提供し、オブジェクトと KeyVaultRoleAssignment オブジェクトのKeyVaultRoleDefinition管理を可能にします。

KeyVaultBackupClient

には KeyVaultBackupClient 、完全キー バックアップ、完全キー復元、選択的キー復元を実行するための同期操作と非同期操作の両方が用意されています。

BackupOperation

は BackupOperation 、完全キー バックアップの実行時間の長い操作を表します。

RestoreOperation

は RestoreOperation 、完全キー復元と選択的キー復元の両方に対する実行時間の長い操作を表します。

スレッド セーフ

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

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

例

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

次のセクションでは、アクセス制御またはバックアップ クライアントに対して上記で作成した をclient使用して、最も一般的な Azure Key Vault アクセス制御関連タスクの一部をカバーするいくつかのコード スニペットを示します。

同期の例

非同期の例

トラブルシューティング

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

全般

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

たとえば、Azure Key Vaultに存在しないロールの割り当てを取得しようとすると、404"Not Found" を示すエラーが返されます。

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

コンソール ログの設定

ログを表示する最も簡単な方法は、コンソール ログを有効にすることです。 コンソールにメッセージを出力する Azure SDK ログ リスナーを作成するには、 メソッドを使用します AzureEventSourceListener.CreateConsoleLogger 。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

その他のログメカニズムの詳細については、 こちらを参照してください。

次の手順

サンプルを使用して作業を開始します。

共同作成

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

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

インプレッション数