Клиентская библиотека секретов Azure Key Vault для JavaScript версии 4.3.0

Azure Key Vault — это служба, которая позволяет шифровать ключи проверки подлинности, ключи учетной записи хранения, ключи шифрования данных, PFX-файлы и пароли с помощью защищенных ключей. Если вы хотите узнать больше о Key Vault Azure, ознакомьтесь с разделом Что такое Azure Key Vault?

Управление секретами Key Vault Azure позволяет безопасно хранить маркеры, пароли, сертификаты, ключи API и другие секреты, а также строго контролировать доступ к ним.

Используйте клиентную библиотеку секретов Key Vault Azure в приложении Node.js, чтобы:

• Получение, установка и удаление секретов.
• Обновите секрет и его атрибуты.
• Резервное копирование и восстановление секрета.
• Получение, очистка или восстановление удаленного секрета.
• Получение всех версий секрета.
• Получение всех секретов.
• Получение всех удаленных секретов.

Примечание. Этот пакет нельзя использовать в браузере из-за ограничений службы Azure Key Vault. См. этот документ для получения рекомендаций.

Основные ссылки:

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

Начало работы

Поддерживаемые в настоящее время среды

• LTS версии Node.js

Предварительные требования

• Подписка Azure
• Ресурс Key Vault

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

Установите клиентную библиотеку Секрета Key Vault Azure с помощью npm:

npm install @azure/keyvault-secrets

Установка библиотеки удостоверений

Key Vault клиенты проходят проверку подлинности с помощью библиотеки удостоверений Azure. Установите его также с помощью npm.

npm install @azure/identity

Настройка TypeScript

Для пользователей TypeScript необходимо установить определения типов Node:

npm install @types/node

Также необходимо включить compilerOptions.allowSyntheticDefaultImports в файле tsconfig.json. Обратите внимание, что если вы включили compilerOptions.esModuleInteropпараметр , allowSyntheticDefaultImports он включен по умолчанию. Дополнительные сведения см. в руководстве по параметрам компилятора TypeScript .

Настройка Key Vault

Используйте приведенный ниже фрагмент Cloud Shell Azure, чтобы создать или получить учетные данные секрета клиента.

• Создайте субъект-службу и настройте его доступ к ресурсам Azure:

  az ad sp create-for-rbac -n <your-application-name> --skip-assignment
  

  Выходные данные:

  {
    "appId": "generated-app-ID",
    "displayName": "dummy-app-name",
    "name": "http://dummy-app-name",
    "password": "random-password",
    "tenant": "tenant-ID"
  }
  

• Используйте указанные выше учетные данные, чтобы задать переменные среды AZURE_CLIENT_ID(appId), AZURE_CLIENT_SECRET(password) и AZURE_TENANT_ID(tenant). В следующем примере показано, как это сделать в Bash:

    export AZURE_CLIENT_ID="generated-app-ID"
    export AZURE_CLIENT_SECRET="random-password"
    export AZURE_TENANT_ID="tenant-ID"
  

• Предоставьте упомянутому выше приложению авторизацию для выполнения операций с секретами в хранилище ключей:

  az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --secret-permissions backup delete get list purge recover restore set
  

  --secret-permissions: принятые значения: backup, delete, get, list, purge, recover, restore, set

  Если вместо этого вы включили управление доступом на основе ролей (RBAC) для Key Vault, вы можете найти такие роли, как "Key Vault Secrets Officer" в нашем руководстве по RBAC.

• Используйте указанное выше имя Key Vault, чтобы получить сведения о хранилище, которое также содержит url-адрес Key Vault:

  az keyvault show --name <your-key-vault-name>
  

Основные понятия

• Клиент Secret — это основной интерфейс для взаимодействия с методами API, связанными с секретами в API azure Key Vault из приложения JavaScript. После инициализации он предоставляет базовый набор методов, которые можно использовать для создания, чтения, обновления и удаления секретов.
• Версия секрета — это версия секрета в Key Vault. Каждый раз, когда пользователь присваивает значение уникальному имени секрета, создается новая версия этого секрета. При извлечении секрета по имени всегда возвращается последнее назначенное значение, если в запросе не указана определенная версия.
• Обратимое удаление позволяет Key Vault поддерживать удаление и очистку в виде двух отдельных шагов, поэтому удаленные секреты не теряются сразу. Это происходит, только если в Key Vault включено обратимое удаление.
• Резервная копия секрета может быть создана из любого созданного секрета. Эти резервные копии поступают в виде двоичных данных и могут использоваться только для повторного создания ранее удаленного секрета.

Проверка подлинности с помощью Azure Active Directory

Служба Key Vault использует Azure Active Directory для проверки подлинности запросов к своим API. Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. Файл сведений для @azure/identity содержит дополнительные сведения и примеры для начала работы.

Вот краткий пример. Сначала импортируйте DefaultAzureCredential и SecretClient:

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

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

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

// 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();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our secrets client and connect to the service
const client = new SecretClient(url, credential);

Указание версии API службы azure Key Vault

По умолчанию этот пакет использует последнюю версию службы Key Vault Azure— 7.1. Поддерживается 7.0только другая версия . Вы можете изменить используемую версию службы, задав параметр serviceVersion в конструкторе клиента, как показано ниже:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0"
});

Примеры

В следующих разделах приведены фрагменты кода, в которые рассматриваются некоторые распространенные задачи, связанные с использованием секретов azure Key Vault. Описанные здесь сценарии состоят из следующих:

• Создание и установка секрета.
• Получение секрета.
• Создание и обновление секретов с помощью атрибутов.
• Удаление секрета.
• Итерации списков секретов.

Создание и задание секрета

setSecret присваивает указанное значение указанному имени секрета. Если секрет с таким именем уже существует, создается новая версия секрета.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Получение секрета

Самый простой способ считывания секретов из хранилища — получить секрет по имени. При этом будет извлечена последняя версия секрета. При необходимости можно получить другую версию ключа, если указать ее в качестве части необязательных параметров.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

Создание и обновление секретов с помощью атрибутов

Секрет может содержать больше сведений, чем его имя и значение. Они также могут включать следующие атрибуты:

• tags: любой набор "ключ-значение", который можно использовать для поиска и фильтрации секретов.
• contentType: любая строка, которая может использоваться, чтобы помочь получателю секрета понять, как использовать значение секрета.
• enabled: логическое значение, определяющее, можно ли считать значение секрета.
• notBefore: заданная дата, после которой можно получить значение секрета.
• expires: заданная дата, после которой невозможно получить значение секрета.

Объект с этими атрибутами можно отправить в качестве третьего setSecretпараметра , сразу после имени и значения секрета, как показано ниже:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false
  });
}

main();

При этом будет создана новая версия того же секрета, которая будет содержать последние предоставленные атрибуты.

Атрибуты также можно обновить до существующей версии секрета с updateSecretPropertiesпомощью , как показано ниже.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

Удаление секрета

Метод beginDeleteSecret запускает удаление секрета. Этот процесс будет выполняться в фоновом режиме, как только будут доступны необходимые ресурсы.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Если для Key Vault включено обратимое удаление, эта операция пометит секрет только как удаленный секрет. Удаленный секрет не может быть обновлен. Их можно только прочитать, восстановить или очистить.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

Так как полное удаление секретов занимает некоторое время, возвращает объект Poller, beginDeleteSecret который отслеживает базовую долго выполняющуюся операцию в соответствии с нашими рекомендациями: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Полученное средство опроса позволит получить удаленный секрет путем вызова poller.getResult(). Вы также можете подождать, пока удаление завершится, выполнив отдельные вызовы служб до удаления секрета или дождавшись завершения процесса.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

Еще один способ дождаться полного удаления секрета — выполнить отдельные вызовы, как показано ниже.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

Итерации списков секретов

С помощью SecretClient можно получить и выполнить итерацию по всем секретам в Key Vault, а также по всем удаленным секретам и версиям определенного секрета. Доступны следующие методы API:

• listPropertiesOfSecrets выводит список всех неудаляемых секретов по именам, только в последних версиях.
• listDeletedSecrets выводит список всех удаленных секретов по именам, только в последних версиях.
• listPropertiesOfSecretVersions выводит список всех версий секрета на основе имени секрета.

Который можно использовать следующим образом:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

main();

Все эти методы возвращают все доступные результаты одновременно. Чтобы получить их по страницам, добавьте .byPage() сразу после вызова метода API, который вы хотите использовать, следующим образом:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

Устранение неполадок

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Дальнейшие действия

Дополнительные примеры кода можно найти по следующим ссылкам:

• Примеры секретов KeyVault (JavaScript)
• Примеры секретов KeyVault (TypeScript)
• Тестовые случаи секретов KeyVault

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.