JavaScript 用 Azure Key Vault 管理クライアント ライブラリ - バージョン 4.5.0

  • [アーティクル]

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

パッケージ@azure/keyvault-adminは、完全バックアップ/復元、キー レベルのロールベースのアクセス制御 (RBAC) などの管理Key Vaultタスクをサポートします。

注: 管理ライブラリは Azure Key Vault Managed HSM でのみ機能します。Key Vaultを対象とする関数は失敗します。

注: このパッケージは、Azure Key Vault サービスの制限によりブラウザーで使用できません。ガイダンスについては、こちらのドキュメントを参照してください。

主要リンク:

作業の開始

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

NPM を使用して JavaScript と TypeScript 用の Azure Key Vault管理クライアント ライブラリをインストールします。

npm install @azure/keyvault-admin

TypeScript の構成

TypeScript ユーザーには、ノードの種類の定義がインストールされている必要があります。

npm install @types/node

また、tsconfig.jsonで を有効にする compilerOptions.allowSyntheticDefaultImports 必要があります。 を有効compilerOptions.esModuleInteropallowSyntheticDefaultImportsにした場合、既定では が有効になっていることに注意してください。 詳細については、「 TypeScript のコンパイラ オプション ハンドブック 」を参照してください。

現在サポートされている環境

前提条件

クライアントを認証する

Azure Key Vault サービスと対話するには、クラスまたは KeyVaultBackupClient クラスのKeyVaultAccessControlClientインスタンスと、コンテナー URL (Azure Portal で "DNS 名" と表示される場合があります) と資格情報オブジェクトを作成する必要があります。 このドキュメントに示す例では、 という名前 DefaultAzureCredentialの資格情報オブジェクトを使用します。これは、ローカルの開発環境や運用環境を含むほとんどのシナリオに適しています。 また、運用環境での認証には マネージド ID を 使用することをお勧めします。

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

KeyVaultAccessControlClient を作成する

最適な認証方法で認証したら、次のように を作成KeyVaultAccessControlClientし、コンストラクターの Managed HSM URL に置き換えることができます。

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyVaultAccessControlClient } = require("@azure/keyvault-admin");

const credentials = new DefaultAzureCredential();

const client = new KeyVaultAccessControlClient(`<your Managed HSM URL>`, credentials);

KeyVaultBackupClient を作成する

最適な認証方法で認証したら、次のように を作成KeyVaultBackupClientし、コンストラクターの Managed HSM URL に置き換えることができます。

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyVaultBackupClient } = require("@azure/keyvault-admin");

const credentials = new DefaultAzureCredential();

const client = new KeyVaultBackupClient(`<your Managed HSM URL>`, credentials);

主要な概念

KeyVaultRoleDefinition

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

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

KeyVaultRoleAssignment

ロールの割り当ては、サービス プリンシパルへのロール定義の関連付けです。 これらは、個別に作成、一覧表示、フェッチ、および削除できます。

KeyVaultAccessControlClient

には KeyVaultAccessControlClient 、ロール定義 (のインスタンス) とロールの割り当て (の KeyVaultRoleDefinitionインスタンス) の管理を可能にする操作が用意されています KeyVaultRoleAssignment。

KeyVaultBackupClient

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

長時間の操作

によって実行される KeyVaultBackupClient 操作には、Azure リソースで必要なだけ時間がかかる場合があります。クライアント 層は、完了を待つプログラムのライフサイクルを通じて操作を追跡、シリアル化、再開する必要があります。 これは、パッケージ @azure/core-lro を通じて共通の抽象化によって行われます。

には KeyVaultBackupClient 、実行時間の長い操作を実行する 3 つのメソッドが用意されています。

  • beginBackupでは、指定したストレージ BLOB アカウントで Azure Key Vault Managed HSM のバックアップの生成が開始されます。
  • beginRestoreは、以前に格納された Azure Blob Storage バックアップ フォルダーを指す SAS トークンを使用して、すべてのキーマテリアルの復元を開始します。
  • beginSelectiveRestoreは、以前に格納された Azure Blob Storage バックアップ フォルダーを指すユーザー指定の SAS トークンを使用して、特定のキーのすべてのキー バージョンの復元を開始します。

実行時間の長い操作を開始するメソッドは、操作が完了するまで無期限に待機できるポーリングャーを返します。 詳細については、以下の例を参照してください。

例

このパッケージのアクセス制御とバックアップ/復元機能を示す JavaScript と TypeScript の両方のサンプルがあります。 サンプルを実行する詳細な手順については、対応する readmes に従ってください。

トラブルシューティング

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

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。 または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

次のステップ

その他のコード サンプルについては、次のリンクを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数