快速入门：适用于 JavaScript 的Azure Key Vault托管 HSM 客户端库

开始使用适用于 JavaScript 的 Azure Key Vault 托管 HSM 客户端库。托管 HSM 是一种完全托管、高度可用、符合标准的单租户云服务，可用于使用 FIPS 140-3 级别 3 验证的 HSM 来保护云应用程序的加密密钥。有关托管 HSM 的详细信息，请查看概述。

在本快速入门中，你将了解如何使用 JavaScript 客户端库访问和执行托管 HSM 中的密钥的加密操作。

托管 HSM 客户端库资源：

API 参考文档 | Library 源代码 | Package （npm）

先决条件

一个Azure订阅。免费创建一个。
预配和激活的托管 HSM。请参阅 Quickstart：使用 Azure CLI 预配和激活托管 HSM。
在托管 HSM 中创建的密钥。请参阅托管 HSM 中的“管理密钥”。
具有托管标识的Azure资源（例如 VM、应用服务或Azure 函数），或用于本地开发的Azure CLI。
必须为托管标识分配适当的托管 HSM 本地 RBAC 角色。请参阅安全访问托管的 HSM。

Node.js 18 LTS 或更高版本

设置本地环境

本快速入门使用 Azure 身份验证库与 Azure CLI 来为 Azure 服务进行身份验证。开发人员还可以使用Visual Studio Code对调用进行身份验证。有关详细信息，请参阅使用Azure标识客户端库对客户端进行身份验证。

az login运行命令以登录：

az login

创建项目文件夹并初始化

创建项目文件夹并导航到它：
```
mkdir mhsm-js-app && cd mhsm-js-app
```
初始化项目：
```
npm init -y
```

安装软件包

安装Azure标识和Key Vault密钥客户端库：

npm install @azure/identity @azure/keyvault-keys

创建示例代码

创建包含以下代码的文件 index.js 。将 <hsm-name> 替换为托管 HSM 名称，并将 <key-name> 替换为现有的密钥名称。

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");

async function main() {
    // Use DefaultAzureCredential for automatic credential selection
    const credential = new DefaultAzureCredential();

    // Connect to Managed HSM - replace with your HSM URI
    const hsmUri = "https://<hsm-name>.managedhsm.chinacloudapi.cn";
    const keyClient = new KeyClient(hsmUri, credential);

    // Get a key reference
    const keyName = "<key-name>";
    console.log(`Retrieving key '${keyName}' from Managed HSM...`);
    const key = await keyClient.getKey(keyName);
    console.log(`Key retrieved. Key type: ${key.keyType}`);

    // Perform cryptographic operations
    const cryptoClient = new CryptographyClient(key, credential);

    // Encrypt data
    const plaintext = Buffer.from("Hello, Managed HSM!");
    console.log(`\nOriginal text: ${plaintext.toString()}`);

    const encryptResult = await cryptoClient.encrypt("RSA-OAEP-256", plaintext);
    console.log(`Encrypted (base64): ${encryptResult.result.toString("base64").substring(0, 64)}...`);

    // Decrypt data
    const decryptResult = await cryptoClient.decrypt("RSA-OAEP-256", encryptResult.result);
    console.log(`Decrypted text: ${decryptResult.result.toString()}`);

    console.log("\nDone!");
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

运行应用程序

运行应用程序：

node index.js

此时会看到与下面类似的输出：

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (base64): NWE4ZjNiMmMxZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNGM...
Decrypted text: Hello, Managed HSM!

Done!

了解数据

使用 DefaultAzureCredential 进行身份验证

DefaultAzureCredential 根据环境自动选择相应的凭据：

环境	使用的凭据
Azure VM、应用服务、函数	系统分配的或用户分配的托管标识
Azure Kubernetes 服务	工作负载标识
地方发展	Azure CLI、Visual Studio 或 VS Code 凭据
CI/CD 管道	工作负荷标识联合或服务主体

凭证按顺序检查这些来源：

环境变量
工作负载标识
托管标识
Azure CLI
Azure PowerShell
Visual Studio/VS Code 凭证

对于Azure中的生产工作负荷，强烈建议使用托管标识，因为它们完全消除了凭据管理。

关键操作

该 KeyClient 类提供以下方法：

创建、获取、更新和删除密钥
列出密钥和密钥版本
备份和还原密钥

该 CryptographyClient 类提供加密操作：

加密和解密数据
签名和验证签名
包装和解包密钥

分配托管 HSM 角色

若要使您的应用程序访问密钥，请将适当的本地 RBAC 角色分配给您的托管 HSM 标识:

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name myVM --resource-group myRG --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name ContosoMHSM \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

若需了解角色和权限的更多信息，请参阅托管 HSM 本地 RBAC 内置角色。

清理资源

如果不再需要资源组和所有相关资源，请将其删除：

az group delete --name <resource-group>

警告

删除资源组会将托管 HSM 置于软删除状态。托管 HSM 将继续计费，直到被清理为止。请参阅托管 HSM 软删除和清除保护

后续步骤

Last updated on 2026-04-22

共用方式為