快速入门：适用于 JavaScript 的 Azure Key Vault 密钥客户端库

项目
06/02/2023

适用于 JavaScript 的 Azure Key Vault 密钥客户端库入门。 Azure Key Vault 是一项云服务，它为加密密钥提供了安全的存储。可以安全地存储密钥、密码、证书和其他机密。可以通过 Azure 门户创建和管理 Azure Key Vault。本快速入门介绍如何使用 JavaScript 密钥客户端库在 Azure 密钥保管库中创建、检索和删除密钥

Key Vault 客户端库资源：

API 参考文档 | 库源代码 | 包 (npm)

有关 Key Vault 和密钥的详细信息，请参阅：

Key Vault 概述
密钥概述。

先决条件

Azure 订阅 - 创建试用版订阅。
当前 Node.js LTS。
Azure CLI
现有的 Key Vault - 可以使用以下方法创建一个：

本快速入门假设你运行 Azure CLI。

运行 login 命令。
```
az cloud set -n AzureChinaCloud
az login
```
如果 CLI 可以打开默认浏览器，它将这样做并加载 Azure 登录页。

否则，请在 https://aka.ms/deviceloginchina 处打开浏览器页，然后输入终端中显示的授权代码。
在浏览器中使用帐户凭据登录。

创建新的 Node.js 应用程序

创建一个使用密钥保管库的 Node.js 应用程序。

在终端中，创建一个名为 key-vault-node-app 的文件夹并更改为该文件夹：
```
mkdir key-vault-node-app && cd key-vault-node-app
```
初始化 Node.js 项目：
```
npm init -y
```

安装 Key Vault 包

使用终端安装 Azure Key Vault 机密客户端库（适用于 Node.js 的 @azure/keyvault-keys）。
```
npm install @azure/keyvault-keys
```
安装 Azure 标识客户端库（@azure.identity 包）以对密钥保管库进行身份验证。
```
npm install @azure/identity
```

授予对 Key Vault 的访问权限

针对密钥保管库创建一个访问策略，以便为用户帐户授予密钥权限

az keyvault set-policy --name <YourKeyVaultName> --upn user@domain.com --key-permissions delete get list create update purge

设置环境变量

此应用程序使用 Key Vault 名称作为名为 KEY_VAULT_NAME 的环境变量。

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

export KEY_VAULT_NAME=<your-key-vault-name>

进行身份验证并创建客户端

对大多数 Azure 服务的应用程序请求必须获得授权。要在代码中实现与 Azure 服务的无密码连接，推荐使用由 Azure 标识客户端库提供的 DefaultAzureCredential 方法。 DefaultAzureCredential 支持多种身份验证方法，并确定应在运行时使用哪种方法。通过这种方法，你的应用可在不同环境（本地与生产）中使用不同的身份验证方法，而无需实现特定于环境的代码。

在本快速入门中，DefaultAzureCredential 使用登录到 Azure CLI 的本地开发用户的凭据对密钥保管库进行身份验证。将应用程序部署到 Azure 时，相同的 DefaultAzureCredential 代码可以自动发现并使用分配给应用服务、虚拟机或其他服务的托管标识。有关详细信息，请参阅托管标识概述。

在此代码中，密钥保管库的名称用于创建密钥保管库 URI，格式为 https://<your-key-vault-name>.vault.azure.cn。有关向密钥保管库进行身份验证的详细信息，请参阅开发人员指南。

代码示例

以下代码示例演示如何创建客户端以及设置、检索和删除机密。

此代码使用以下密钥保管库机密类和方法：

设置应用框架

创建新文本文件并将以下代码粘贴到 index.js 文件中。

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

async function main() {

    // DefaultAzureCredential expects the following three environment variables:
    // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
    // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
    // - AZURE_CLIENT_SECRET: The client secret for the registered application
    const credential = new DefaultAzureCredential();

    const keyVaultName = process.env["KEY_VAULT_NAME"];
    if(!keyVaultName) throw new Error("KEY_VAULT_NAME is empty");
    const url = "https://" + keyVaultName + ".vault.azure.cn";

    const client = new KeyClient(url, credential);

    const uniqueString = Date.now();
    const keyName = `sample-key-${uniqueString}`;
    const ecKeyName = `sample-ec-key-${uniqueString}`;
    const rsaKeyName = `sample-rsa-key-${uniqueString}`;

    // Create key using the general method
    const result = await client.createKey(keyName, "EC");
    console.log("key: ", result);

    // Create key using specialized key creation methods
    const ecResult = await client.createEcKey(ecKeyName, { curve: "P-256" });
    const rsaResult = await client.createRsaKey(rsaKeyName, { keySize: 2048 });
    console.log("Elliptic curve key: ", ecResult);
    console.log("RSA Key: ", rsaResult);

    // Get a specific key
    const key = await client.getKey(keyName);
    console.log("key: ", key);

    // Or list the keys we have
    for await (const keyProperties of client.listPropertiesOfKeys()) {
    const key = await client.getKey(keyProperties.name);
    console.log("key: ", key);
    }

    // Update the key
    const updatedKey = await client.updateKeyProperties(keyName, result.properties.version, {
    enabled: false
    });
    console.log("updated key: ", updatedKey);

    // Delete the key - the key is soft-deleted but not yet purged
    const deletePoller = await client.beginDeleteKey(keyName);
    await deletePoller.pollUntilDone();

    const deletedKey = await client.getDeletedKey(keyName);
    console.log("deleted key: ", deletedKey);

    // Purge the key - the key is permanently deleted
    // This operation could take some time to complete
    console.time("purge a single key");
    await client.purgeDeletedKey(keyName);
    console.timeEnd("purge a single key");
}

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

运行示例应用程序

运行应用：
```
node index.js
```

create 和 get 方法为密钥返回完整的 JSON 对象：

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-NAME.vault.azure.cn/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-NAME.vault.azure.cn/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME.vault.azure.cn",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-NAME.vault.azure.cn/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

与应用配置集成

Azure SDK 提供了一个帮助程序方法 parseKeyVaultKeyIdentifier，用于解析给定的 Key Vault 密钥 ID。如果使用对 Key Vault 的应用配置引用，则此方法是必须的。应用配置存储 Key Vault 密钥 ID。需要 parseKeyVaultKeyIdentifier 方法来解析该 ID 以获取密钥名称。获得密钥名称后，可以使用本快速入门中的代码获取当前的密钥值。

后续步骤

在本快速入门中，你创建了一个密钥保管库，存储了一个密钥，然后检索了该密钥。若要详细了解 Key Vault 以及如何将其与应用程序集成，请继续阅读以下文章。