Краткое руководство: библиотека клиента ключей Azure Key Vault для JavaScript

Начало работы с клиентской библиотекой ключей Azure Key Vault для JavaScript. Azure Key Vault — это облачная служба, которая предоставляет защищенное хранилище для ключей шифрования. Вы можете безопасно хранить ключи, пароли, сертификаты и другие секреты. Создать хранилища Azure Key Vault и управлять ими можно на портале Azure. Из этого краткого руководства вы узнаете, как создавать, извлекать и удалять ключи из хранилища ключей Azure с помощью клиентской библиотеки ключей JavaScript.

Ресурсы клиентской библиотеки Key Vault:

Справочная документация по API | Исходный код библиотеки | Пакет (npm).

Дополнительные сведения о Key Vault и ключах см. в следующих статьях:

Требования

Подписка Azure — создайте бесплатную учетную запись.
Текущая Node.js LTS.
Azure CLI
Существующее хранилище ключей — его можно создать с помощью:

Подписка Azure — создайте бесплатную учетную запись.
Текущая Node.js LTS.
TypeScript 5+
Azure CLI.
Существующее хранилище ключей — его можно создать с помощью:

В этом кратком руководстве предполагается, что вы используете Azure CLI.

Выполните команду login.
```
az login
```
Если CLI может открыть ваш браузер по умолчанию, он откроет его и загрузит страницу входа в Azure.

В противном случае самостоятельно откройте в браузере страницу https://aka.ms/devicelogin и введите код авторизации, отображаемый в терминале.
Выполните вход в браузере с помощью учетных данных.

Создание приложения 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, @azure/keyvault-keys для Node.js.
```
npm install @azure/keyvault-keys
```
Установите клиентскую библиотеку Azure Identity, пакет @azure/identity, чтобы выполнить аутентификацию в Key Vault.
```
npm install @azure/identity
```

Предоставление доступа к хранилищу ключей

Чтобы получить разрешения для хранилища ключей с помощью контроль доступа на основе ролей (RBAC), назначьте роль для "User Principal Name" (UPN) с помощью команды az role assignment create.

az role assignment create --role "Key Vault Crypto Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/<vault-name>"

Замените <upn>, <subscription-id>а <vault-name> также фактическими значениями. Если вы использовали другое имя группы ресурсов, замените myResourceGroup. Ваше имя пользователя (UPN) обычно имеет формат адреса электронной почты, например username@domain.com.

Настройка переменных среды

Это приложение использует конечную точку хранилища ключей в качестве переменной окружения KEY_VAULT_URL.

set KEY_VAULT_URL=<key-vault-endpoint>

Windows PowerShell

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

export KEY_VAULT_URL=<key-vault-endpoint>

Аутентификация и создание клиента

Запросы приложений к большинству служб Azure должны быть авторизованы. Использование метода DefaultAzureCredential, предоставленного библиотекой клиента идентификации Azure, является рекомендуемым подходом для реализации подключений к службам Azure без пароля в вашем коде. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

В этом кратком руководстве DefaultAzureCredential происходит аутентификация в хранилище ключей с использованием учетных данных пользователя-разработчика, подключенного к Azure CLI. При развертывании приложения в Azure тот же DefaultAzureCredential код может автоматически обнаруживать и использовать управляемое удостоверение, назначенное службе приложений, виртуальной машине или другим службам. Дополнительные сведения см. в разделе Обзор управляемых удостоверений.

В этом коде конечная точка вашего хранилища ключей используется для создания клиентского приложения хранилища ключей. Формат конечной точки, такой как https://<vault-name>.vault.azure.net, может изменяться для суверенных облаков. Дополнительные сведения о проверке подлинности в хранилище ключей см. в руководстве для разработчиков.

Пример кода

В приведенных ниже примерах кода показано, как создать клиент, задать ключ, получить ключ и удалить ключ.

Этот код использует следующие классы и методы Key Vault Key:

Настройка платформы приложения

Создайте новый текстовый файл и вставьте приведенный ниже код в файл 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);
});

Запуск примера приложения

Запустите приложение:
```
node index.js
```

Методы создания и получения возвращают полный объект JSON в ключе:

"key":  {
  "key": {
    "kid": "https://<your-key-vault-name>.vault.azure.net/keys/<your-key-name>/<key-version>",
    "kty": "RSA",
    "keyOps": [ "encrypt", "decrypt", "sign", "verify", "wrapKey", "unwrapKey" ],
    ... other properties based on key type
  },
  "id": "https://<your-key-vault-name>.vault.azure.net/keys/<your-key-name>/<key-version>",
  "name": "<your-key-name>",
  "keyOperations": [ "encrypt", "decrypt", "sign", "verify", "wrapKey", "unwrapKey" ],
  "keyType": "RSA",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2025-11-29T18:29:11.000Z,
    "updatedOn": 2025-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://<your-key-vault-name>.vault.azure.net",
    "version": "<key-version>",
    "name": "<your-key-name>",
    "managed": undefined,
    "id": "https://<your-key-vault-name>.vault.azure.net/keys/<your-key-name>/<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);
});

Запуск примера приложения

Создайте приложение TypeScript:
```
tsc
```
Запустите приложение:
```
node index.js
```

Методы создания и получения возвращают полный объект JSON в ключе:

"key":  {
  "key": {
    "kid": "https://<your-key-vault-name>.vault.azure.net/keys/<your-key-name>/<key-version>",
    "kty": "RSA",
    "keyOps": [ "encrypt", "decrypt", "sign", "verify", "wrapKey", "unwrapKey" ],
    ... other properties based on key type
  },
  "id": "https://<your-key-vault-name>.vault.azure.net/keys/<your-key-name>/<key-version>",
  "name": "<your-key-name>",
  "keyOperations": [ "encrypt", "decrypt", "sign", "verify", "wrapKey", "unwrapKey" ],
  "keyType": "RSA",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2025-11-29T18:29:11.000Z,
    "updatedOn": 2025-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://<your-key-vault-name>.vault.azure.net",
    "version": "<key-version>",
    "name": "<your-key-name>",
    "managed": undefined,
    "id": "https://<your-key-vault-name>.vault.azure.net/keys/<your-key-name>/<key-version>"
  }
}

Интеграция со службой "Конфигурация приложений"

Пакет SDK Azure предоставляет вспомогательный метод — parseKeyVaultKeyIdentifier для анализа заданного идентификатора ключа Key Vault. Это необходимо, если вы используете Конфигурация приложений как ссылки на Key Vault. В конфигурации приложений хранится идентификатор ключа Key Vault. Чтобы получить имя ключа, необходимо выполнить анализ этого идентификатора с помощью метода parseKeyVaultKeyIdentifier. Получив имя ключа, можно получить текущее значение ключа с использованием кода из этого краткого руководства.

Следующие шаги

Из этого краткого руководства вы узнали, как создать хранилище ключей, сохранить в нем ключ и извлечь его. Чтобы узнать больше о Key Vault и о том, как интегрировать его с приложениями, перейдите к этим статьям.

Прочитайте Обзор Azure Key Vault
Прочитайте обзор ключей Azure Key Vault
Безопасный доступ к хранилищу ключей
Ознакомьтесь с рекомендациями по обеспечению безопасности для определенных ключей
Руководство разработчика Azure Key Vault
Статья Обзор системы безопасности Key Vault

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-09

Краткое руководство: библиотека клиента ключей Azure Key Vault для JavaScript

Требования

Вход в Azure

Создание приложения Node.js

Установка пакетов Key Vault

Предоставление доступа к хранилищу ключей

Настройка переменных среды

Аутентификация и создание клиента

Пример кода

Настройка платформы приложения

Запуск примера приложения

Запуск примера приложения

Интеграция со службой "Конфигурация приложений"

Следующие шаги

Обратная связь

Дополнительные ресурсы