你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 密钥保管库机密客户端库 - 版本 4.8.0

项目
02/26/2024

Azure 密钥保管库是一项服务，可用于使用安全密钥加密身份验证密钥、存储帐户密钥、数据加密密钥、.pfx 文件和密码。若要详细了解 Azure 密钥保管库，可能需要查看：什么是 Azure 密钥保管库？

使用 Azure 密钥保管库机密管理，可以安全地存储和严格控制对令牌、密码、证书、API 密钥和其他机密的访问。

在 Node.js 应用程序中使用 Azure 密钥保管库机密的客户端库可以：

获取、设置和删除机密。
更新机密及其属性。
备份和还原机密。
获取、清除或恢复已删除的机密。
获取机密的所有版本。
获取所有机密。
获取所有已删除的机密。

注意：由于 Azure 密钥保管库服务限制，无法在浏览器中使用此包，请参阅此文档以获取指导。

关键链接：

入门

目前支持的环境

LTS 版本的 Node.js

先决条件

Azure 订阅
密钥保管库资源
现有的 Azure 密钥保管库。如果需要创建密钥保管库，可以在 Azure 门户中按照本文档中的步骤操作。或者，可以按照本文档中的步骤使用 Azure CLI。

安装包

使用 npm 安装 Azure 密钥保管库机密客户端库：

npm install @azure/keyvault-secrets

安装标识库

密钥保管库客户端使用 Azure 标识库进行身份验证。也使用 npm 安装它

npm install @azure/identity

配置 TypeScript

TypeScript 用户需要安装 Node 类型定义：

npm install @types/node

还需要在tsconfig.json中启用 compilerOptions.allowSyntheticDefaultImports 。请注意，如果已启用 compilerOptions.esModuleInterop， allowSyntheticDefaultImports 则默认启用。有关详细信息，请参阅 TypeScript 的编译器选项手册。

关键概念

机密客户端是与 JavaScript 应用程序中的 Azure 密钥保管库 API 中的机密相关的 API 方法进行交互的主要接口。初始化后，它将提供一组可用于创建、读取、更新和删除机密的基本方法。
机密版本是密钥保管库中的机密版本。每次用户向唯一机密名称分配值时，都会创建该机密的 新版本 。除非向查询提供特定版本，否则按名称检索机密将始终返回分配的最新值。
软删除 允许 Key Vault 支持将删除和清除作为两个单独的步骤，因此删除的机密不会立即丢失。仅当密钥保管库启用了软删除时，才会发生这种情况。
可以从任何创建的 机密生成机密备份 。这些备份以二进制数据的形式提供，只能用于重新生成以前删除的机密。

使用 Azure Active Directory 进行身份验证

密钥保管库服务依赖于 Azure Active Directory 对其 API 的请求进行身份验证。 @azure/identity 包提供应用程序可用于执行此操作的各种凭据类型。的自述文件 @azure/identity 提供了更多详细信息和示例来帮助你入门。

若要与 Azure 密钥保管库服务交互，需要创建类的SecretClient实例、保管库 URL 和凭据对象。本文档中显示的示例使用名为的 DefaultAzureCredential凭据对象，该对象适用于大多数方案，包括本地开发和生产环境。此外，我们建议使用托管标识在生产环境中进行身份验证。

可以在 Azure 标识文档中找到有关不同身份验证方式及其相应凭据类型的详细信息。

下面是一个快速示例。首先，导入 DefaultAzureCredential 和 SecretClient：

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

导入这些服务后，接下来可以连接到密钥保管库服务：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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);

指定 Azure 密钥保管库服务 API 版本

默认情况下，此包使用最新的 Azure 密钥保管库服务版本，即 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 密钥保管库机密的一些常见任务。此处介绍的方案包括：

创建和设置机密。
获取机密。
使用属性创建和更新机密。
删除机密。
迭代机密列表。

创建和设置机密

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：一个给定的日期，在此日期之后可以检索机密值。
expiresOn：一个给定日期，在此日期之后无法检索机密值。

具有这些属性的对象可以作为的第三个 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 开始删除机密。一旦必要资源可用，此过程就会在后台发生。

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

如果为密钥保管库启用了软删除，则此操作只会将机密标记为已删除的机密。无法更新已删除的机密。只能读取、恢复或清除它们。

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

由于机密需要一些时间才能完全删除，因此返回一个 Poller 对象， beginDeleteSecret 该对象根据我们的准则跟踪基础长时间运行操作： 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();

等待机密完全删除的另一种方法是执行单个调用，如下所示：

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

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，可以检索和循环访问密钥保管库中的所有机密，以及所有已删除的机密和特定机密的版本。以下 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");

后续步骤

可以通过以下链接找到更多代码示例：

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

曝光数

通过

适用于 JavaScript 的 Azure 密钥保管库 机密客户端库 - 版本 4.8.0

入门