Azure Key Vault Secret client library for JavaScript - version 4.11.0

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

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

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

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

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

Ключевые ссылки:

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

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

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

Версии Node.js LTS

Предпосылки

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

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

Install the Azure Key Vault Secret client library using npm:

npm install @azure/keyvault-secrets

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

Клиенты Key Vault аутентифицируются с помощью Azure Identity Library. Установите его, а также с помощью npm

npm install @azure/identity

Настройка TypeScript

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

npm install @types/node

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

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

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

Authenticating with Azure Active Directory

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

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

Более подробную информацию о различных способах аутентификации и соответствующих типах учетных данных можно найти в Azure Identity documentation.

Вот краткий пример. Сначала импортируйте DefaultAzureCredential и SecretClient. После импорта мы можем подключиться к сервису Key Vault:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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);

Для сред браузера используйте InteractiveBrowserCredential из пакета @azure/identity для проверки подлинности.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

Спецификация версии API Azure Key Vault service

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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`;

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

Примеры

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

Если soft-delete включена для Key Vault, эта операция будет маркировать секрет только как deleted секрет. Не удается обновить удаленный секрет. Они могут быть доступны только для чтения, восстановления или очистки.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

Ознакомьтесь с нашим руководством по устранению неполадок для подробностей диагностики различных сценариев отказа.

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

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

setLogLevel("info");

Дальнейшие шаги

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

Вклад

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

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

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

Last updated on 2026-04-08