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

2025-06-13

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

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

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

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

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

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

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

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

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

Версии Node.js LTS

Предпосылки

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

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

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

npm install @azure/keyvault-secrets

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

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

npm install @azure/identity

Настройка TypeScript

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

npm install @types/node

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

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

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

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

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

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

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

Вот краткий пример. Сначала импортируйте 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 keys client and connect to the service
const client = new SecretClient(url, credential);

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

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

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

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

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

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

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

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

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

Вклад

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