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

2025-06-13

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

Пакет @azure/keyvault-admin обеспечивает поддержку административных задач Key Vault, таких как полное резервное копирование и восстановление и управление доступом на основе ролей на уровне ключа (RBAC).

Примечание. Библиотека администрирования работает только с управляемых HSM Azure Key Vault. Функции, предназначенные для Key Vault, завершаются сбоем.

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

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

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

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

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

Установите клиентскую библиотеку администрирования Azure Key Vault для JavaScript и TypeScript с NPM:

npm install @azure/keyvault-admin

Настройка TypeScript

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

npm install @types/node

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

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

Версии Node.js LTS

Предпосылки

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

аутентификация клиента;

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

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

Создание KeyVaultAccessControlClient

После проверки подлинности с помощью метода проверки подлинности, который подходит для вас лучше всего, можно создать KeyVaultAccessControlClient следующим образом, подстановку в URL-адрес управляемого HSM в конструкторе:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyVaultAccessControlClient } from "@azure/keyvault-admin";

const vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
const credentials = new DefaultAzureCredential();
const client = new KeyVaultAccessControlClient(vaultUrl, credentials);

Создание KeyVaultBackupClient

После проверки подлинности с помощью метода проверки подлинности, который подходит для вас лучше всего, можно создать KeyVaultBackupClient следующим образом, подстановку в URL-адрес управляемого HSM в конструкторе:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyVaultBackupClient } from "@azure/keyvault-admin";

const vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
const credentials = new DefaultAzureCredential();
const client = new KeyVaultBackupClient(vaultUrl, credentials);

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

Определение роли KeyVault

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

Определения ролей можно перечислить и указать как часть KeyVaultRoleAssignment.

KeyVaultRoleAssignment

Назначение ролей — это связь определения роли с субъектом-службой. Их можно создавать, перечислять, получать по отдельности и удалять.

KeyVaultAccessControlClient (Ключ VaultAccessControlClient)

KeyVaultAccessControlClient предоставляет операции, позволяющие управлять определениями ролей (экземплярами KeyVaultRoleDefinition) и назначениями ролей (экземплярами KeyVaultRoleAssignment).

KeyVaultBackupClient (Клиент резервного копирования)

KeyVaultBackupClient предоставляет операции для выполнения полного резервного копирования ключей, восстановления полного ключа и выборочного восстановления ключей.

Длительные операции

Операции, выполняемые KeyVaultBackupClient, могут занять столько времени, сколько потребуется ресурсам Azure, требуя от уровня клиента отслеживать, сериализовать и возобновлять операции через жизненный цикл программ, которые ожидают их завершения. Это делается с помощью общей абстракции через пакет @azure/core-lro.

KeyVaultBackupClient предлагает три метода выполнения длительных операций:

beginBackup, начинает создавать резервную копию управляемого HSM Azure Key Vault в указанной учетной записи BLOB-объектов хранилища.
beginRestore, начинает восстановление всех ключевых материалов с помощью маркера SAS, указывающего на ранее сохраненную папку резервного копирования хранилища BLOB-объектов Azure.
beginSelectiveRestoreначинает восстановление всех версий ключа заданного ключа с помощью предоставленного пользователем маркера SAS, указывающего на ранее сохраненную папку резервного копирования хранилища BLOB-объектов Azure.

Методы, начинающие длительные операции, возвращают опрашиватель, который позволяет ждать неограниченное время до завершения операции. Дополнительные сведения см. в приведенных ниже примерах.

Примеры

У нас есть примеры в JavaScript и TypeScript, которые показывают функции управления доступом и резервного копирования и восстановления в этом пакете. Чтобы выполнить примеры, выполните соответствующие инструкции чтения.

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

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

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

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

setLogLevel("info");

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

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

Вклад

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