Azure Key Vault Secret client library for JavaScript - version 4.11.1

Azure Key Vaultは、認証キー、ストレージアカウントキー、データ暗号化キー、.pfxファイル、パスワードをセキュアキーを使って暗号化できるサービスです。 Azure Key Vaultについてもっと知りたい場合は、Azure Key Vaultとは何か?

Azure Key Vault Secrets管理は、トークン、パスワード、証明書、APIキー、その他の秘密へのアクセスを安全に保存し厳密に管理することを可能にします。

Node.js アプリケーション内のAzure Key Vaultシークレットのクライアントライブラリを活用して:

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

注:このパッケージはAzure Key Vaultサービスの制限によりブラウザ上で使用できません。this documentを参照してください。

主要なリンク:

作業の開始

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

Node.js の LTS バージョン

[前提条件]

Azureサブスクリプション
Key Vaultリソース
既存のAzure Key Vault。キーボールトを作成する場合は、このドキュメントの手順に従ってAzure portalで作成できます。または、このドキュメントの手順に従ってAzure CLIを使うこともできます。

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

npmを使ってAzure Key Vault Secretクライアントライブラリをインストールしてください:

npm install @azure/keyvault-secrets

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

Key VaultクライアントはAzure Identity Libraryを使って認証します。 npm を使用してインストールする

npm install @azure/identity

TypeScript の構成

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

npm install @types/node

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

重要な概念

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

Azure Active Directoryでの認証

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

Azure Key Vaultサービスとやり取りするには、SecretClientクラスのインスタンス、vault url、そして認証オブジェクトを作成する必要があります。このドキュメントに示す例では、DefaultAzureCredentialという名前の資格情報オブジェクトを使用します。これは、ローカルの開発環境や運用環境など、ほとんどのシナリオに適しています。さらに、運用環境での認証には、マネージド ID を使用することをお勧めします。

認証方法やそれに対応する資格の種類については、Azure Identity documentationで詳細をご覧いただけます。

簡単な例を次に示します。まず、DefaultAzureCredential と SecretClientをインポートします。これらがインポートされた後、次にKey Vaultサービスに接続できます:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

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);

ブラウザー環境では、InteractiveBrowserCredential パッケージの @azure/identity を使用して認証します。

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

Specificationifying the Azure Key Vault service API version

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
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", // Or 7.1
});

例示

以下のセクションでは、Azure Key Vault Secretsを使った一般的なタスクの一部をカバーしたコードスニペットを提供します。ここで説明するシナリオは、次のもので構成されます。

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

シークレットの取得

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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,
);

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

シークレットを削除する

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

soft-deleteがKey Vaultで有効の場合、この操作はシークレットをdeletedシークレットとしてのみラベル付けします。削除されたシークレットは更新できません。読み取り、回復、または消去のみが可能です。

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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);

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

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

SecretClientを使えば、Key Vault内のすべての秘密、削除されたすべての秘密、特定の秘密のバージョンを取得・順次確認できます。次の API メソッドを使用できます。

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

トラブルシューティング

さまざまな故障シナリオの診断方法については、トラブルシューティングガイドをご覧ください。

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

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

setLogLevel("info");

次のステップ

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

投稿

このライブラリに貢献したい場合は、コードのビルドやテスト方法について詳しく知るために、contributing guideをお読みください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-09