适用于 JavaScript 的 Azure Key Vault 管理客户端库 - 版本 4.7.0

Azure Key Vault 托管 HSM 是一种完全托管、高度可用的单租户标准云服务，可用于使用 FIPS 140-2 级别 3 验证的 HSM 来保护云应用程序的加密密钥。 若要详细了解 Azure Key Vault 托管 HSM，可能需要查看：什么是 Azure Key Vault 托管 HSM？

包 @azure/keyvault-admin 为管理 Key Vault 任务提供支持，例如完整备份/还原和密钥级基于角色的访问控制（RBAC）。

注意：管理库仅适用于 Azure Key Vault 托管 HSM - 面向 Key Vault 的函数将失败。

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

关键链接：

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

入门指南

安装软件包

使用 NPM安装适用于 JavaScript 和 TypeScript 的 Azure Key Vault 管理客户端库：

npm install @azure/keyvault-admin

配置 TypeScript

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

npm install @types/node

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

当前支持的环境

• LTS 版本的 Node.js

先决条件

• 一个 Azure 订阅
• 现有的 Key Vault 托管 HSM。 如果需要创建托管 HSM，可以按照本文档 中的步骤使用 Azure CLI。

对客户端进行身份验证

若要与 Azure Key Vault 服务交互，需要创建 KeyVaultAccessControlClient 类或 KeyVaultBackupClient 类的实例，以及 保管库 URL（Azure 门户中可能显示为“DNS 名称”）和凭据对象。 本文档中显示的示例使用名为 DefaultAzureCredential的凭据对象，该对象适用于大多数方案，包括本地开发和生产环境。 此外，我们建议在生产环境中使用 托管标识 进行身份验证。

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

创建 KeyVaultAccessControlClient

使用 最适合的身份验证方法进行身份验证后，可以按如下所示创建 KeyVaultAccessControlClient，在构造函数的托管 HSM URL 中替换：

import { DefaultAzureCredential } from "@azure/identity";
import { KeyVaultAccessControlClient } from "@azure/keyvault-admin";

const vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
const credentials = new DefaultAzureCredential();
const client = new KeyVaultAccessControlClient(vaultUrl, credentials);

创建 KeyVaultBackupClient

使用 最适合的身份验证方法进行身份验证后，可以按如下所示创建 KeyVaultBackupClient，在构造函数的托管 HSM URL 中替换：

import { DefaultAzureCredential } from "@azure/identity";
import { KeyVaultBackupClient } from "@azure/keyvault-admin";

const vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
const credentials = new DefaultAzureCredential();
const client = new KeyVaultBackupClient(vaultUrl, credentials);

重要概念

KeyVaultRoleDefinition

角色定义是权限的集合。 角色定义定义可以执行的作，例如读取、写入和删除。 它还可以定义从允许的作中排除的作。

角色定义可以列出并指定为 KeyVaultRoleAssignment的一部分。

KeyVaultRoleAssignment 密钥库角色分配

角色分配是角色定义与服务主体的关联。 可以单独创建、列出、提取和删除它们。

KeyVaultAccessControl客户端

KeyVaultAccessControlClient 提供允许管理角色定义（KeyVaultRoleDefinition实例）和角色分配（KeyVaultRoleAssignment实例）的作。

KeyVaultBackupClient

KeyVaultBackupClient 提供用于执行完整密钥备份、完整密钥还原和选择性密钥还原的作。

长时间运行的操作

KeyVaultBackupClient 完成的作可能需要 Azure 资源所需的时间，这需要客户端层跟踪、序列化和恢复作，这些作在等待这些作完成的程序的生命周期中。 这是通过包 @azure/core-lro的常见抽象完成的。

KeyVaultBackupClient 提供了三种执行长时间运行的作的方法：

• beginBackup，开始在指定的存储帐户上生成 Azure Key Vault 托管 HSM 的备份。
• beginRestore，开始使用指向以前存储的 Azure Blob 存储备份文件夹的 SAS 令牌还原所有密钥材料。
• beginSelectiveRestore，开始使用用户提供的 SAS 令牌还原给定密钥的所有密钥版本，这些令牌指向以前存储的 Azure Blob 存储备份文件夹。

开始长时间运行作的方法返回一个轮询器，该轮询器允许无限期等待作完成。 以下示例中提供了详细信息。

例子

我们提供了 JavaScript 和 TypeScript 中的示例，用于显示此包中的访问控制和备份/还原功能。 有关运行示例的详细步骤，请遵循相应的自述文件。

• JavaScript 示例的自述文件
• typeScript 示例 自述文件

故障排除

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

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

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

setLogLevel("info");

后续步骤

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

• Key Vault 管理示例 （JavaScript）
• Key Vault 管理示例（TypeScript）
• Key Vault 管理测试用例

贡献

若要参与此库，请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。