Поделиться через


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

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

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

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

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

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

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

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

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

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

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

Установите клиентую библиотеку 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");

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

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

Участие

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

Просмотры