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

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

项目
02/26/2024

Azure 密钥保管库是一种云服务，可安全存储和自动管理整个云应用程序中使用的证书。多个证书和同一证书的多个版本可以保留在 Azure 密钥保管库中。保管库中的每个证书都有一个与之关联的策略，该策略控制证书的颁发和生存期，以及要作为证书即将过期采取的操作。

如果想要详细了解 Azure 密钥保管库，可能需要查看：什么是 Azure 密钥保管库？

在 Node.js 应用程序中使用 Azure 密钥保管库证书的客户端库来：

获取、设置和删除证书。
更新证书、其属性、颁发者、策略、操作和联系人。
备份和还原证书。
获取、清除或恢复已删除的证书。
获取证书的所有版本。
获取所有证书。
获取所有已删除的证书。

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

关键链接：

入门

目前支持的环境

LTS 版本的 Node.js

先决条件

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

安装包

使用 npm 安装 Azure 密钥保管库证书客户端库

npm install @azure/keyvault-certificates

安装标识库

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

npm install @azure/identity

配置 TypeScript

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

npm install @types/node

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

使用 Azure Active Directory 进行身份验证

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

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

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

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

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

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

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

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 certificates client and connect to the service
const client = new CertificateClient(url, credential);

关键概念

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

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

默认情况下，此包使用最新的 Azure 密钥保管库服务版本，即 7.1。唯一支持的其他版本是 7.0。可以通过在客户端构造函数中设置选项 serviceVersion 来更改正在使用的服务版本，如下所示：

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

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 CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

示例

以下部分提供代码片段，涵盖使用 Azure 密钥保管库证书的一些常见任务。此处介绍的方案包括：

创建和设置证书。
获取密钥保管库证书。
获取证书的完整信息。
PEM 格式的证书。
列出所有证书。
更新证书。
正在删除证书。
循环访问证书列表。

创建和设置证书

beginCreateCertificate创建要存储在 Azure 密钥保管库中的证书。如果已存在同名证书，则会创建新版本的证书。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.beginCreateCertificate(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

除了证书和策略的名称外，还可以在第三个参数中传递以下属性，其中包含可选值：

enabled：一个布尔值，用于确定是否可以使用证书。
tags：可用于搜索和筛选证书的任何键值集。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

async function main() {
  await client.beginCreateCertificate(certificateName, certificatePolicy, {
    enabled,
    tags,
  });
}

main();

beginCreateCertificate使用同名调用将创建同一证书的新版本，该证书将具有提供的最新属性。

由于证书需要一些时间才能完全创建， beginCreateCertificate 因此会返回一个轮询器对象，该对象根据我们的准则跟踪基础长时间运行操作： https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

接收的轮询器将允许你通过调用 poller.getResult()来获取创建的证书。还可以等待删除完成，方法是运行单个服务调用，直到创建证书，或等待该过程完成：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  // You can use the pending certificate immediately:
  const pendingCertificate = poller.getResult();

  // Or you can wait until the certificate finishes being signed:
  const keyVaultCertificate = await poller.pollUntilDone();
  console.log(keyVaultCertificate);
}

main();

等待证书签名的另一种方法是执行单个调用，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
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 CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

  console.log(`The certificate ${certificateName} is fully created`);
}

main();

获取密钥保管库证书

从保管库中读取证书的最简单方法是按名称获取证书。 getCertificate 将检索证书的最新版本以及证书的策略。如果指定版本，可以选择通过调用 getCertificateVersion 来获取不同版本的证书。 getCertificateVersion 不返回证书的策略。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const latestCertificate = await client.getCertificate(certificateName);
  console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
  const specificCertificate = await client.getCertificateVersion(
    certificateName,
    latestCertificate.properties.version
  );
  console.log(
    `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
    specificCertificate
  );
}

main();

获取证书的完整信息

Azure 密钥保管库的设计对密钥、机密和证书进行了尖锐的区分。密钥保管库服务的证书功能是利用其密钥和机密功能设计的。让我们评估密钥保管库证书的构成：

创建 Key Vault 证书后，还可以创建具有相同名称的可寻址密钥和机密。 Key Vault 密钥允许密钥操作，Key Vault 机密允许以机密的形式检索证书值。 Key Vault 证书还包含公共 x509 证书元数据。 源：证书的组成。

知道私钥存储在包含公共证书的密钥保管库机密中，我们可以使用密钥保管库机密客户端检索它。

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

请注意，默认情况下，证书的内容类型为 PKCS 12。通过指定证书的内容类型，你将能够以 PEM 格式检索它。在演示如何创建 PEM 证书之前，让我们先了解如何从 PKCS 12 证书检索 PEM 密钥。

使用 openssl，可以使用以下命令检索 PEM 格式的公共证书：

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

还可以使用 openssl 检索私钥，如下所示：

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

请注意，在这两种情况下，openssl 都会要求你提供用于创建证书的密码。到目前为止，我们使用的示例代码尚未指定密码，因此可以追加 -passin 'pass:' 到每个命令的末尾。

PEM 格式的证书

如果要使用 PEM 格式的证书，可以在创建证书时提供 contentType 属性，告知 Azure 的密钥保管库服务以 PEM 格式创建和管理证书。

以下示例演示如何使用证书和机密的密钥保管库客户端创建和检索 PEM 格式证书的公共部分和私有部分：

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

请记住，公共证书将位于与私钥相同的内容 Blob 中。可以使用 PEM 标头相应地提取它们。

列出所有证书

listPropertiesOfCertificates将列出密钥保管库中的所有证书。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

更新证书

证书属性可以使用更新为现有证书版本 updateCertificate，如下所示：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

还可以使用 updateCertificatePolicy单独更新证书的策略，如下所示：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = client.getCertificate(certificateName);
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

删除证书

方法 beginDeleteCertificate 设置要删除的证书。一旦必要资源可用，此过程就会在后台发生。

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

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const poller = await client.beginDeleteCertificate(certificateName);

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

  // The certificate 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 certificate this way:
  await client.getDeletedCertificate(certificateName);

  // Deleted certificates can also be recovered or purged.

  // recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
  // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
  // await recoverPoller.pollUntilDone();

  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

由于删除证书不会立即发生，因此调用方法后 beginDeleteCertificate 需要一些时间，然后才能读取、恢复或清除已删除的证书。

循环访问证书列表

使用 CertificateClient，可以检索和循环访问证书保管库中的所有证书，以及所有已删除的证书和特定证书的版本。以下 API 方法可用：

listPropertiesOfCertificates 将按名称列出所有未删除的证书，仅在最新版本中列出。
listDeletedCertificates 将按名称列出所有已删除的证书，仅在最新版本中列出。
listPropertiesOfCertificateVersions 将基于证书名称列出证书的所有版本。

可按如下方式使用：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
  for await (let deletedCertificate of client.listDeletedCertificates()) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(
    certificateName
  )) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

所有这些方法都将一次性返回 所有可用结果 。若要按页面检索它们，请在调用要使用的 API 方法后立即添加 .byPage() ，如下所示：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let page of client.listPropertiesOfCertificates().byPage()) {
    for (let certificateProperties of page) {
      console.log("Certificate properties: ", certificateProperties);
    }
  }
  for await (let page of client.listDeletedCertificates().byPage()) {
    for (let deletedCertificate of page) {
      console.log("Deleted certificate: ", deletedCertificate);
    }
  }
  for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
    for (let certificateProperties of page) {
      console.log("Properties of certificate: ", certificateProperties);
    }
  }
}

main();

故障排除

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

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

setLogLevel("info");

有关如何诊断各种故障方案的详细信息，请参阅故障排除指南。

后续步骤

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

贡献

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

曝光数