让开源，少一点语言距离。
npm包中文文档

@azure/keyvault-certificates

中文文档
4.11.0发布于 2026/10/28MITTypeScriptESM + CJS近 30 天下载 39.5万

Azure 密钥断层证书

中文使用文档
中文原文
文档目录21 节
  1. 开始
  2. 目前得到支持的环境
  3. 先决条件
  4. 安装软件包
  5. 安装身份库
  6. 配置类型脚本
  7. 正在使用 Azure 活动目录认证
  8. 关键概念
  9. 指定 Azure 密钥默认服务 API 版本
  10. 实例
  11. 创建和设置证书
  12. 获取密钥默认证书
  13. 获取证书的全部信息
  14. PEM 格式的证书
  15. 列出所有证书
  16. 更新证书
  17. 删除证书
  18. 使用证书列表
  19. 解决问题
  20. 今后的步骤
  21. 捐款

JavaScript 的 Azure 密钥默认证书客户端库

Azure Key Vault是一种云端服务,它为整个云端应用程序使用的证书提供安全的存储和自动化管理. 多个证书,以及同一证书的多个版本,都可以被保存在Azure Key Vault. 保险库内的每一份证书都有与此有关的政策,用以控制证书的签发和有效期,以及作为证书即将到期的行动.

如果你想了解更多关于Azure Key Vault的信息,你也许想回顾一下: Azure 键瓦特是什么?

在您的 Node.js 应用程序中使用 Azure 密钥默认证书客户端库:

  • 获取、设置和删除证书.
  • 更新证书、其属性、签发者、政策、操作和联系人.
  • 备份并恢复证书 .
  • 获取、清理或收回已删除的证书.
  • 获取证书的所有版本 .
  • 获取所有证书 .
  • 获取全部已删除的证书 .

说明: 由于 Azure 密钥断层服务限制, 此软件包不能在浏览器中使用, 请参考 此文档 用于指导.

密钥链接 :

开始

目前得到支持的环境

先决条件

安装软件包

使用 npm 安装 Azure 密钥默认证书客户端库

npm install @azure/keyvault-certificates

安装身份库

关键 Vault 客户端使用 Azure 身份库进行认证. 用 npm 安装它

npm install @azure/identity

配置类型脚本

TypeScript 用户需要安装节点类型定义 :

npm install @types/node

您还需要启用 compilerOptions.allowSyntheticDefaultImports 在你的Tsconfig.json中。 请注意, 如果您已启用 compilerOptions.esModuleInterop, (中文(简体) ), allowSyntheticDefaultImports 默认启用。 见 TypeScript 的编译器选项手册 更多信息.

正在使用 Azure 活动目录认证

Key Vault 服务依赖于 Azure Active Directory来认证请求到它的API. 这个 @azure/identity 软件包提供了各种证书类型,应用程序可用来做到这一点。 这个 读取 @azure/identity 提供更多细节和样本来启动.

要与 Azure 键断层服务互动, 您需要创建实例 CertificateClient 类, a 保险库url 和证书对象。 本文档中显示的示例使用命名为证书对象 DefaultAzureCredential,适用于大多数情景,包括当地发展和生产环境。 此外,我们建议使用 管理身份 用于生产环境中的认证.

您可以在数据库中找到更多关于不同认证方式及其相应的证书类型的信息 Azure 身份证件。 。 。 .

这里有一个简单的例子。 第一,导入 DefaultAzureCredential 财务报告和审定财务报表 CertificateClient。一旦这些设备被导入,我们就可连接到密钥金库服务:

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

关键概念

  • 这个 证书客户端 是与 API 方法交互的主要接口 与来自 JavaScript 应用程序的 Azure 键 Vault API 中的证书有关. 一旦初始化,它提供了一套基本方法,可用于 创建、读取、更新和删除证书.
  • A 类 证书版本 是密钥断层中证书的版本. 每次用户给一个唯一的证书名称指定一个值, 一个新 版本 该证书将被创建。 用名称获取证书将永远返回 指定的最新值,除非向 查询.
  • 软删除 允许密钥默认值支持删除和清理为 2 单独步骤,所以删除的证书不会立即丢失。 只有在密钥断层时才会发生 已经 软删除 启用 .
  • A 类 证书备份 可以从创建的证书中生成。 这些备份作为 二进制数据,只能用于再生成之前已删除的证书.

指定 Azure 密钥默认服务 API 版本

默认情况下,此套件使用最新的 Azure 密钥断层服务版本,即 7.1。唯一一个被支持的版本是 7.0。您可以通过设置选项更改正在使用的服务版本 serviceVersion 在客户端构造器中显示如下:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.5",
});

实例

以下各节提供了涵盖部分常见的代码片段 任务使用 Azure 密钥断层证书。 本文涵盖的情景包括:

创建和设置证书

beginCreateCertificate 创建要存储在 Azure 密钥断层的证书 。 若为 已存在同名证书,新版本 证书被创建.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

除了证书和策略的名称,您还可以在第三个带有可选值的参数中传递以下属性:

  • enabled: 确定证书是否可以使用的布尔值.
  • tags: 任意一组可用于搜索和过滤证书的密钥值.
import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

呼吁 beginCreateCertificate 同名将创建一个新版本的 同一证书,该证书将具有最近提供的属性.

由于证书需要一段时间才能完全创建, beginCreateCertificate 返回一个能跟踪下方长跑的传粉器对象 按照我们的准则行动: https://azure.github.io/azure-sdk/typescript dedesign.html#ts-lro (英语)

接受的传票人将允许您通过呼叫获得创建的证书 poller.getResult()。 。 。 . 您也可以通过运行单个服务等待删除完成 调用直到证书创建, 或者等待进程完成:

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

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

另一种等待证书签名的方式是进行个人通话,具体如下:

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

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

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

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

获取密钥默认证书

从金库读回证书最简单的方式就是得到 证书名称. getCertificate 将获取最新的 证书的版本,连同证书的政策。 你们可以 可选择通过调用获取证书的不同版本 getCertificateVersion 如果您指定了版本. getCertificateVersion 不返回 证书的保险单.

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

获取证书的全部信息

Azure Key Vault的设计对Keys作了鲜明的区分, 秘密与证书. 密钥默认服务证书 设计时利用了关键和秘密能力. 让我们来评估密钥断层证书的构成:

当创建密钥默认证书时, 可地址键 秘密也是同名的。 关键错 键允许密钥操作, 而密钥默认密钥允许检索 证书值为密件。 密钥默认证书 也包含公开的x509证书元数据. 资料来源: 证书的构成。 。 。 .

知道私钥存储在密钥断层密钥中, 加上公证书,我们就可以拿回来 通过使用密钥断层密钥客户端.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

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

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// 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:
writeFileSync("myCertificate.p12", PKCS12Certificate);

请注意,默认情况下,证书的内容类型 为 PKCS 12。 通过指定内容类型 证书中,您可以以 PEM 格式检索. 在演示如何创建 PEM 证书之前, 让我们首先探索如何取回 PEM 密钥 首先从 PKCS 12 证书.

使用 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

请注意,在这两种情况下,Opensl都会问你 用于创建证书的密码 。 我们使用的样本代码 目前尚未指定密码, 您可以附加 -passin 'pass:' 到每个命令的结尾.

PEM 格式的证书

如果您想要使用 PEM 格式的证书工作, 您可以告诉 Azure 的密钥断层服务创建和管理您的 以 PEM 格式提供的证书 contentType 属性 在创建证书时.

以下示例显示如何创建和检索 pEM 格式化证书的公共和私人部分 使用证书和密钥默认客户端:

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// 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.
});
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);

记住你的公证书 和你的私密钥匙一样. 您可以使用 PEM 头来提取它们 .

列出所有证书

listPropertiesOfCertificates 将列出密钥断层中的所有证书.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

更新证书

证书属性可通过 updateCertificate,内容如下:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

证书的策略也可以通过下列方式逐一更新: updateCertificatePolicy,内容如下:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

删除证书

这个 beginDeleteCertificate 方法设置要删除的证书。 这一过程将 一旦获得必要的资源,即可在背景中进行.

若为 软删除 启用用于密钥默认值,此操作仅将证书标签为 删除 证书。 无法更新已删除的证书 。 他们只能是 读取、恢复或清洗.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

由于无法立即删除证书,所以需要一些时间 之后 beginDeleteCertificate 方法在删除的证书被调用之前 可读取、回收或清理.

使用证书列表

使用证书Client,您可以检索并覆盖所有 证书默认中的证书,以及所有被删除的证书和证书 特定证书的版本。 现有下列API方法:

  • listPropertiesOfCertificates 将列出您所有未删除的证书,仅列出姓名 在他们的最新版本.
  • listDeletedCertificates 将列出所有被删除的证书, 只有最新的版本.
  • listPropertiesOfCertificateVersions 将列出基于证书的证书的所有版本 名称.

可用如下:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

所有这些方法都会回归 所有现有成果 马上 改为: 按页面检索,添加 .byPage() 在引用了 API 方法之后您 想要使用如下:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

解决问题

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 AZURE_LOG_LEVEL 环境变量改为 info。或者,可以在运行时拨打 setLogLevel 输入 @azure/logger数字 :

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

setLogLevel("info");

看我们的 解决问题指南 详细介绍如何诊断各种故障情况.

今后的步骤

您可以通过下列链接找到更多的代码样本:

捐款

如果您想为图书馆捐钱 请读一下 贡献指南 学习如何构建和测试密码.

版本与发布记录

@azure/keyvault-certificates 共发布 632 个版本，首次发布于 2019/09/12；过去 12 个月发布了 80 个版本。

版本发布日期距今
4.11.0latest2026/10/2810 天前
4.11.0-beta.1beta2026/06/055 个月前
4.10.32026/04/106 个月前
4.10.22026/04/096 个月前
4.10.2-alpha.20260306.1dev2026/03/078 个月前
4.10.2-alpha.20260305.12026/03/068 个月前

关于 @azure/keyvault-certificates 的常见问题

@azure/keyvault-certificates 是什么？

Azure 密钥断层证书

如何安装 @azure/keyvault-certificates？

在项目目录运行 npm install @azure/keyvault-certificates，或使用 pnpm add / yarn add / bun add。

@azure/keyvault-certificates 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@azure/keyvault-certificates 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@azure/keyvault-certificates 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@azure/keyvault-certificates 可以商用吗？

@azure/keyvault-certificates 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@azure/keyvault-certificates 的下载量有多少？

根据 npm 官方下载统计，@azure/keyvault-certificates 在 2026/10/08 – 2026/11/06 这 30 天内被下载 394,502 次，日均约 13,150 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@azure/keyvault-certificates 还在维护吗？

最新版本 4.11.0 发布于 2026/10/28（10 天前）；至今共发布 632 个版本，其中过去 12 个月发布了 80 个；首次发布于 2019/09/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。