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

2023-04-05

Azure Key Vault は、セキュリティで保護されたキーを使用して、認証キー、ストレージアカウントキー、データ暗号化キー、.pfx ファイル、パスワードを暗号化できるサービスです。 Azure Key Vaultの詳細については、「Azure Key Vaultとは」を参照してください。

Azure Key Vault シークレット管理を使用すると、トークン、パスワード、証明書、API キー、その他のシークレットへのアクセスを安全に格納して厳密に制御できます。

Node.js アプリケーションで Azure Key Vault シークレット用のクライアントライブラリを使用して、次の手順を実行します。

シークレットを取得、設定、削除します。
シークレットとその属性を更新します。
シークレットのバックアップと復元。
削除されたシークレットを取得、消去、または回復します。
シークレットのすべてのバージョンを取得します。
すべてのシークレットを取得します。
削除されたすべてのシークレットを取得します。

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

主要リンク:

はじめに

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

Node.js の LTS バージョン

前提条件

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

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

npm install @azure/keyvault-secrets

ID ライブラリをインストールする

Key Vault クライアントは、Azure ID ライブラリを使用して認証します。 npm を使用してインストールする

npm install @azure/identity

TypeScript の構成

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

npm install @types/node

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

Key Vaultの構成

次の Azure Cloud Shell スニペットを使用して、クライアントシークレットの資格情報を作成/取得します。

サービスプリンシパルを作成し、Azure リソースへのアクセスを構成します。

az ad sp create-for-rbac -n <your-application-name> --skip-assignment

出力:

{
  "appId": "generated-app-ID",
  "displayName": "dummy-app-name",
  "name": "http://dummy-app-name",
  "password": "random-password",
  "tenant": "tenant-ID"
}

上記の返された資格情報情報を使用して 、AZURE_CLIENT_ID(appId)、 AZURE_CLIENT_SECRET(password)、 AZURE_TENANT_ID(tenant) 環境変数を設定します。次の例は、Bash でこれを行う方法を示しています。
```
  export AZURE_CLIENT_ID="generated-app-ID"
  export AZURE_CLIENT_SECRET="random-password"
  export AZURE_TENANT_ID="tenant-ID"
```
keyvault に対してシークレット操作を実行するために、上記のアプリケーション承認を付与します。
```
az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --secret-permissions backup delete get list purge recover restore set
```
--secret-permissions: 受け入れ可能な値: バックアップ、削除、取得、一覧表示、消去、回復、復元、設定

代わりに、Key Vaultに対してロールベースのアクセス制御 (RBAC) を有効にしている場合は、RBAC ガイドに "Key Vault Secrets Officer" などのロールがあります。
上記のKey Vault名を使用して、Key Vault URL も含むコンテナーの詳細を取得します。
```
az keyvault show --name <your-key-vault-name>
```

主要な概念

シークレットクライアントは、JavaScript アプリケーションから Azure Key Vault API のシークレットに関連する API メソッドと対話するための主要なインターフェイスです。初期化されると、シークレットの作成、読み取り、更新、削除に使用できる基本的な一連のメソッドが提供されます。
シークレットバージョンは、Key Vault内のシークレットのバージョンです。ユーザーが一意のシークレット名に値を割り当てるたびに、そのシークレットの新しい バージョン が作成されます。名前でシークレットを取得すると、クエリに特定のバージョンが指定されていない限り、常に割り当てられた最新の値が返されます。
論理的な削除 を使用すると、Key Vault では削除と消去を 2 つの個別の手順としてサポートできるため、削除されたシークレットはすぐには失われません。これは、Key Vaultで論理的な削除が有効になっている場合にのみ発生します。
シークレットバックアップは、作成された任意のシークレットから生成できます。これらのバックアップはバイナリデータとして提供され、以前に削除されたシークレットの再生成にのみ使用できます。

Azure Active Directory での認証

Key Vault サービスは、Azure Active Directory を使用して API への要求を認証します。パッケージには @azure/identity 、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。の README @azure/identity には、作業を開始するための詳細とサンプルが用意されています。

簡単な例を次に示します。最初に、とをインポート DefaultAzureCredential します SecretClient。

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

これらをインポートしたら、次に Key Vault サービスに接続できます。これを行うには、接続しているKey Vaultから環境変数にいくつかの設定をコピーする必要があります。環境に入ったら、次のコードを使用してアクセスできます。

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

// DefaultAzureCredential expects the following three environment variables:
// * AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// * AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// * AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our secrets client and connect to the service
const client = new SecretClient(url, credential);

Azure Key Vault サービス API バージョンの指定

既定では、このパッケージでは最新の Azure Key Vault サービスバージョン () が使用されます7.1。サポートされている他のバージョンはのみです 7.0。次に示すように、クライアントコンストラクターでオプション serviceVersion を設定することで、使用されているサービスのバージョンを変更できます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0"
});

例

次のセクションでは、Azure Key Vault シークレットを使用する一般的なタスクの一部をカバーするコードスニペットについて説明します。ここで説明するシナリオは、次のもので構成されています。

シークレットの作成と設定。
シークレットの取得。
属性を使用したシークレットの作成と更新。
シークレットの削除。
シークレットの一覧を反復処理する。

シークレットの作成と設定

setSecret は、指定された値を指定されたシークレット名に割り当てます。同じ名前のシークレットが既に存在する場合は、シークレットの新しいバージョンが作成されます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

シークレットの取得

コンテナーからシークレットを読み取り戻す最も簡単な方法は、名前でシークレットを取得することです。これにより、シークレットの最新バージョンが取得されます。オプションのパラメーターの一部としてキーを指定する場合は、必要に応じて別のバージョンのキーを取得できます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

属性を使用したシークレットの作成と更新

シークレットには、名前とその値よりも多くの情報を含めることができます。また、次の属性を含めることもできます。

tags: シークレットの検索とフィルター処理に使用できる任意のキー値のセット。
contentType: シークレットの受信者がシークレット値の使用方法を理解するのに役立つ任意の文字列。
enabled: シークレット値を読み取ることができるかどうかを決定するブール値。
notBefore: シークレット値を取得できる日付を指定します。
expires: シークレット値を取得できない日付。

これらの属性を持つオブジェクトは、の 3 番目の setSecretパラメーターとして、シークレットの名前と値の直後に次のように送信できます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false
  });
}

main();

これにより、同じシークレットの新しいバージョンが作成され、最新の属性が提供されます。

属性は、次のようにを使用 updateSecretPropertiesして既存のシークレットバージョンに更新することもできます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

シークレットを削除する

メソッドは beginDeleteSecret 、Secret の削除を開始します。このプロセスは、必要なリソースが利用可能になるとすぐにバックグラウンドで行われます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Key Vaultに対して論理的な削除が有効になっている場合、この操作ではシークレットに削除されたシークレットとしてのみラベルが付けられます。削除されたシークレットは更新できません。読み取り、回復、または消去のみが可能です。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

シークレットが完全に削除されるまでに時間がかかるため、 beginDeleteSecret ガイドラインに従って基になる長時間実行操作を追跡する Poller オブジェクトを返します。 https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

受信したポーリングャーを使用すると、を呼び出して削除されたシークレットを poller.getResult()取得できます。また、シークレットが削除されるまで個々のサービス呼び出しを実行するか、プロセスが完了するまで待機することで、削除が完了するまで待機することもできます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

シークレットが完全に削除されるまで待機するもう 1 つの方法は、次のように個々の呼び出しを行うことです。

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
const { delay } = require("@azure/core-http");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

シークレットのリストの反復処理

SecretClient を使用すると、Key Vault内のすべてのシークレットを取得して反復処理できるほか、削除されたすべてのシークレットと特定のシークレットのバージョンを通じて反復処理できます。次の API メソッドを使用できます。

listPropertiesOfSecrets は、削除されていないすべてのシークレットを名前で一覧表示し、最新バージョンでのみ表示します。
listDeletedSecrets は、削除されたすべてのシークレットを最新バージョンでのみ、その名前で一覧表示します。
listPropertiesOfSecretVersions では、シークレット名に基づいてシークレットのすべてのバージョンが一覧表示されます。

次のように使用できます。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

main();

これらのメソッドはすべて、 使用可能なすべての結果を 一度に返します。ページごとに取得するには、使用する API メソッドを呼び出した直後に、次のようにを追加 .byPage() します。

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

トラブルシューティング

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

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

次のステップ

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

共同作成

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

インプレッション数