Azure 密钥保管库 Secret client library for JavaScript - version 4.11.0

Azure 密钥保管库 是一项服务，允许你使用安全密钥加密认证密钥、存储账户密钥、数据加密密钥、.pfx 文件和密码。 如果你想了解更多关于Azure 密钥保管库的信息，可以参考：什么是Azure 密钥保管库？

Azure 密钥保管库 密钥管理允许您安全存储并严格控制对令牌、密码、证书、API 密钥及其他密钥的访问。

在您的 Node.js 应用中使用客户端库中的Azure 密钥保管库秘密，以实现：

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

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

关键链接：

• 源代码
• 包 (npm)
• API 参考文档
• 产品文档
• Samples

入门指南

当前支持的环境

• LTS 版本的 Node.js

先决条件

• Azure订阅
• 一个密钥保管库资源
• 一个现有的Azure 密钥保管库。 如果你需要创建密钥库，可以在Azure 门户中按照this document中的步骤来实现。 或者，您也可以按照本文档中的步骤使用该Azure CLI。

安装软件包

使用 npm 安装 Azure 密钥保管库 Secret client library ：

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 的编译器选项手册。

重要概念

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

Authenticating with Azure Active Directory

密钥保管库 服务依赖于 Azure Active Directory 来认证其 API 请求。 @azure/identity 包提供了应用程序可用于执行此操作的各种凭据类型。 的README提供了更多细节和示例，帮助你入门。

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

您可以在Azure身份证明中找到关于不同认证方式及其对应凭证类型的更多信息。

下面是一个快速示例。 首先，导入 DefaultAzureCredential 和 SecretClient。 导入完成后，我们就可以接着连接到 密钥保管库 服务：

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 密钥保管库 service API version

默认情况下，该包使用最新的Azure 密钥保管库服务版本，即 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 密钥保管库 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的第三个参数发送到机密的名称和值之后，如下所示：

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，该操作只会将该秘密标记为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);

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

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，你可以检索并遍历 密钥保管库 中的所有秘密，以及所有已删除的秘密和特定秘密的版本。 可以使用以下 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);
  }
}

故障排除

请参阅我们的 troubleshooting guide，了解如何诊断各种故障情景。

启用日志记录可能有助于发现有关故障的有用信息。 若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。 或者，可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录：

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

setLogLevel("info");

后续步骤

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

• 密钥保管库 秘密示例（JavaScript）
• 密钥保管库 Secrets Samples （TypeScript）
• 密钥保管库 秘密测试案例

贡献

如果你想为本库贡献内容，请阅读 贡献指南，了解更多关于如何构建和测试代码的信息。