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

Мақала
08/07/2024

Начало работы с клиентской библиотекой ключей 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 можно запустить браузер по умолчанию, откроется браузер со страницей входа.

В противном случае самостоятельно откройте в браузере страницу 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, @azure/пакет удостоверений для проверки подлинности в Key Vault.
```
npm install @azure/identity
```

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

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

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>> фактическими значениями.< Имя участника-участника обычно будет иметь формат адреса электронной почты (например, username@domain.com).

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

Это приложение использует конечную точку хранилища ключей в качестве переменной 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 должны быть авторизованы. Использование метода DefaultAzureCredential, предоставленного клиентской библиотекой удостоверений Azure, является рекомендуемым подходом для реализации бессерверных подключений к службам Azure в коде. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

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

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

Пример кода

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

В этом коде используются следующие классы и методы Секрета Key Vault:

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

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

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

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

Методы создания и получения возвращают полный объект 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"
  }
}

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

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

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

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

Бөлісу құралы:

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

Необходимые компоненты

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

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

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

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

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

Пример кода

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

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

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

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

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

Кері байланыс

Қосымша ресурстар

Бөлісу құралы:

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

Необходимые компоненты

Вход в Azure

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

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

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

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

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

Пример кода

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

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

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

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

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

Кері байланыс

Қосымша ресурстар