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

项目
12/18/2024

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

Key Vault 客户端库资源：

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

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

先决条件

Azure 订阅 - 创建试用版订阅。
当前 Node.js LTS。
Azure CLI

先决条件

Azure 订阅 - 创建试用版订阅。
当前 Node.js LTS。
TypeScript 5+
Azure CLI。

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

运行 login 命令。
```
az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.
```
如果 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-secrets）。
```
npm install @azure/keyvault-secrets
```
安装 Azure 标识库（@azure/identity 包）以对密钥保管库进行身份验证。
```
npm install @azure/identity
```

若要通过基于角色的访问控制 (RBAC) 授予应用程序对密钥保管库的权限，请使用 Azure CLI 命令 az role assignment create 分配角色。

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

若要通过基于角色的访问控制 (RBAC) 授予应用程序对密钥保管库的权限，请使用 Azure PowerShell cmdlet New-AzRoleAssignment 分配角色。

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

将 <app-id>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name> 替换为实际值。 <app-id> 是在 Azure Entra 中注册的应用程序的应用程序（客户端）ID。

设置环境变量

此应用程序使用密钥保管库终结点作为名为 KEY_VAULT_URL 的环境变量。

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export KEY_VAULT_URL=<your-key-vault-endpoint>

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

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

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

在此代码中，密钥保管库的终结点用于创建密钥保管库客户端。终结点格式类似于 https://<your-key-vault-name>.vault.azure.cn，但可能会根据不同的主权云而变化。有关向密钥保管库进行身份验证的详细信息，请参阅开发人员指南。

代码示例

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

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

设置应用框架

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

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

async function main() {
  // If you're using MSI, DefaultAzureCredential should "just work".
  // Otherwise, DefaultAzureCredential expects the following three environment variables:
  // - AZURE_TENANT_ID: The tenant ID in Microsoft Entra ID
  // - 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 keyVaultUrl = process.env["KEY_VAULT_URL"];
  if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

  const client = new SecretClient(keyVaultUrl, credential);

  // Create a secret
  // The secret can be a string of any kind. For example,
  // a multiline text block such as an RSA private key with newline characters,
  // or a stringified JSON object, like `JSON.stringify({ mySecret: 'MySecretValue'})`.
  const uniqueString = new Date().getTime();
  const secretName = `secret${uniqueString}`;
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);

  // Read the secret we created
  const secret = await client.getSecret(secretName);
  console.log("secret: ", secret);

  // Update the secret with different attributes
  const updatedSecret = await client.updateSecretProperties(secretName, result.properties.version, {
    enabled: false
  });
  console.log("updated secret: ", updatedSecret);

  // Delete the secret immediately without ability to restore or purge.
  await client.beginDeleteSecret(secretName);
}

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

运行示例应用程序

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

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

{
    "value": "MySecretValue",
    "name": "secret1637692472606",
    "properties": {
        "createdOn": "2021-11-23T18:34:33.000Z",
        "updatedOn": "2021-11-23T18:34:33.000Z",
        "enabled": true,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn",
        "version": "YOUR-VERSION",
        "name": "secret1637692472606"
    }
}

update 方法返回 properties 名称/值对：

"createdOn": "2021-11-23T18:34:33.000Z",
"updatedOn": "2021-11-23T18:34:33.000Z",
"enabled": true,
"recoverableDays": 90,
"recoveryLevel": "Recoverable+Purgeable",
"id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

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

import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
} from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

// Passwordless credential
const credential = new DefaultAzureCredential();

// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

function printSecret(secret: KeyVaultSecret): void {
  const { name, value, properties } = secret;
  const { enabled, expiresOn, createdOn } = properties;
  console.log("Secret: ", { name, value, enabled, expiresOn, createdOn });
}
function printSecretProperties(secret: SecretProperties): void {
  const { name, enabled, expiresOn, createdOn } = secret;
  console.log("Secret: ", { name, enabled, expiresOn, createdOn });
}

async function main(): Promise<void> {
  // Create a new SecretClient
  const client = new SecretClient(keyVaultUrl, credential);

  // Create a unique secret name
  const uniqueString = new Date().getTime().toString();
  const secretName = `secret${uniqueString}`;

  // Create a secret
  const createSecretResult = await client.setSecret(
    secretName,
    "MySecretValue"
  );
  printSecret(createSecretResult);

  // Get the secret by name
  const getSecretResult = await client.getSecret(secretName);
  printSecret(getSecretResult);

  // Update properties
  const updatedSecret = await client.updateSecretProperties(
    secretName,
    getSecretResult.properties.version,
    {
      enabled: false,
    }
  );
  printSecretProperties(updatedSecret);

  // Delete secret (without immediate purge)
  const deletePoller = await client.beginDeleteSecret(secretName);
  await deletePoller.pollUntilDone();
}

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

运行示例应用程序

构建 TypeScript 应用：
```
tsc
```
运行应用：
```
node index.js
```

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

{
    "value": "MySecretValue",
    "name": "secret1637692472606",
    "properties": {
        "createdOn": "2021-11-23T18:34:33.000Z",
        "updatedOn": "2021-11-23T18:34:33.000Z",
        "enabled": true,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn",
        "version": "YOUR-VERSION",
        "name": "secret1637692472606"
    }
}

update 方法返回 properties 名称/值对：

"createdOn": "2021-11-23T18:34:33.000Z",
"updatedOn": "2021-11-23T18:34:33.000Z",
"enabled": true,
"recoverableDays": 90,
"recoveryLevel": "Recoverable+Purgeable",
"id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

与应用配置集成

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

后续步骤

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

通过

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

先决条件

先决条件

登录 Azure

创建新的 Node.js 应用程序

安装 Key Vault 包

授予对 Key Vault 的访问权限

设置环境变量

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

代码示例

设置应用框架

运行示例应用程序

运行示例应用程序

与应用配置集成

后续步骤

其他资源