Compartilhar via

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

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

Key Vault客户端库资源：

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

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

先决条件

本快速入门假定你正在运行 Azure CLI。

登录到 Azure

  1. 运行 login 命令。

    az login

    如果 CLI 可以打开默认浏览器，它将执行此作并加载Azure登录页。

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

  2. 在浏览器中使用帐户凭据登录。

创建新的 Node.js 应用程序

创建使用key vault的 Node.js 应用程序。

  1. 在终端中，创建一个名为 key-vault-node-app 的文件夹并更改为该文件夹：

    mkdir key-vault-node-app && cd key-vault-node-app

  2. 初始化 Node.js 项目：

    npm init -y

安装 Key Vault 软件包

  1. 使用终端安装Azure Key Vault密钥客户端库，@azure/keyvault-keys for Node.js。

    npm install @azure/keyvault-keys

  2. 安装Azure标识客户端库，@azure/identity 包以向Key Vault进行身份验证。

    npm install @azure/identity

向您的密钥库授予访问权限

若要通过 Role-Based Access Control （RBAC）获取key vault的权限，请使用 Azure CLI 命令 az role assignment create 将角色分配给“用户主体名称”（UPN）。

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

将 <upn>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name> 替换为你的实际值。 你的 UPN 通常采用电子邮件地址格式（例如 username@domain.com）。

设置环境变量

此应用程序使用 key vault 终结点作为名为 KEY_VAULT_URL 的环境变量。

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

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

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

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

在此代码中，密钥保管库的终结点用于创建密钥保管库客户端。 终结点格式类似于 https://<your-key-vault-name>.vault.azure.cn，但对于专用云可能会更改。 有关向 key vault 进行身份验证的详细信息，请参阅 Developer 指南。

代码示例

下面的代码示例将演示如何创建客户端、设置密钥、检索密钥和删除密钥。

此代码使用以下Key Vault键类和方法：

设置应用框架

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

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

async function main() {

    // DefaultAzureCredential automatically uses managed identity in Azure environments.
    // For local development, it uses credentials from Azure CLI, Azure PowerShell, or environment variables.
    // See: https://learn.microsoft.com/javascript/api/@azure/identity/defaultazurecredential
    const credential = new DefaultAzureCredential();

    const keyVaultUrl = process.env["KEY_VAULT_URL"];
    if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

    const client = new KeyClient(keyVaultUrl, 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);
});

运行示例应用程序

  1. 运行应用：

    node index.js

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

    "key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/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-ENDPOINT/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-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

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


import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
} from "@azure/keyvault-keys";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

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 printKey(keyVaultKey: KeyVaultKey): void {
  const { name, key, id, keyType, keyOperations, properties } = keyVaultKey;
  console.log("Key: ", { name, key, id, keyType });

  const { vaultUrl, version, enabled, expiresOn }: KeyProperties = properties;
  console.log("Key Properties: ", { vaultUrl, version, enabled, expiresOn });

  console.log("Key Operations: ", keyOperations.join(", "));
}

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

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

  // Create a EC key
  const ecKey = await client.createKey(keyName, "EC");
  printKey(ecKey);

  // Elliptic curve key
  const ec256Key = await client.createEcKey(ecKeyName, {
    curve: "P-256",
  });
  printKey(ec256Key);

  // RSA key
  const rsa2048Key = await client.createRsaKey(rsaKeyName, {
    keySize: 2048,
  });
  printKey(rsa2048Key);

  // Get a key
  const key = await client.getKey(keyName);
  printKey(key);

  // Get properties of all keys
  for await (const keyProperties of client.listPropertiesOfKeys()) {
    const iteratedKey = await client.getKey(keyProperties.name);
    printKey(iteratedKey);
  }

  // Update key properties - disable key
  const updatedKey = await client.updateKeyProperties(
    keyName,
    ecKey.properties.version,
    {
      enabled: false,
    }
  );
  printKey(updatedKey);

  // Delete key (without immediate purge)
  const deletePoller = await client.beginDeleteKey(keyName);
  await deletePoller.pollUntilDone();

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

  // Purge a deleted key
  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);
});

运行示例应用程序

  1. 构建 TypeScript 应用：

    tsc

  2. 运行应用：

    node index.js

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

    "key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/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-ENDPOINT/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-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

与 App Configuration 集成

Azure SDK 提供帮助程序方法（parseKeyVaultKeyIdentifier）来分析给定的Key Vault密钥 ID。 如果您使用应用配置对密钥保管库的引用，则需要这样做。 应用配置存储Key Vault密钥 ID。 需要 parseKeyVaultKeyIdentifier 方法来解析该 ID 以获取密钥名称。 获得密钥名称后，可以使用本快速入门中的代码获取当前的密钥值。

后续步骤

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

  • Last updated on