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

Статья
02/16/2024

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

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

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

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

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

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

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

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

LTS версии Node.js

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

Подписка Azure
Ресурс Key Vault
Существующий Key Vault Azure. Если вам нужно создать хранилище ключей, это можно сделать на портале Azure, выполнив действия, описанные в этом документе. Кроме того, можно использовать Azure CLI, выполнив действия, описанные в этом документе.

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

Установите клиентую библиотеку Azure Key Vault Secret с помощью 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 .

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

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

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

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

Чтобы взаимодействовать со службой azure Key Vault, необходимо создать экземпляр SecretClient класса , URL-адрес хранилища и объект учетных данных. В примерах, приведенных в этом документе, используется объект учетных данных с именем DefaultAzureCredential, который подходит для большинства сценариев, включая локальные среды разработки и рабочие среды. Кроме того, мы рекомендуем использовать управляемое удостоверение для проверки подлинности в рабочих средах.

Дополнительные сведения о различных способах проверки подлинности и соответствующих типах учетных данных см. в документации по удостоверениям Azure.

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

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

После импорта мы можем подключиться к службе Key Vault:

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

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 службы Key Vault Azure

По умолчанию этот пакет использует последнюю версию службы azure Key Vault, которая — 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: заданная дата, после которой можно получить значение секрета.
expiresOn: заданная дата, после которой невозможно получить значение секрета.

Объект с этими атрибутами можно отправить в качестве третьего 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();

Так как полное удаление секретов занимает некоторое время, beginDeleteSecret возвращает объект Poller, который отслеживает базовую длительную операцию в соответствии с нашими рекомендациями: 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-util");

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");

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

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

Участие

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

Просмотры