Azure Key Vault Certificates client library for JavaScript - version 4.10.3

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

Если вы хотите узнать больше о Azure Key Vault, возможно, стоит ознакомиться: Что такое Azure Key Vault?

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

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

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

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

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

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

Необходимые условия

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

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

Install the Azure Key Vault Certificates client library using npm

npm install @azure/keyvault-certificates

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

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

npm install @azure/identity

Настройка TypeScript

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

npm install @types/node

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

Authenticating with Azure Active Directory

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

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

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

Вот краткий пример. Сначала импортируйте DefaultAzureCredential и CertificateClient. После импорта этих данных можно подключиться к службе хранилища ключей:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

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 certificates client and connect to the service
const client = new CertificateClient(url, credential);

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

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 CertificateClient(url, credential, {
  serviceVersion: "7.5",
});

Примеры

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

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

beginCreateCertificate создаёт сертификат, который будет храниться в Azure Key Vault. Если сертификат с тем же именем уже существует, создается новая версия сертификата.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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

  • enabled: логическое значение, определяющее, можно ли использовать сертификат.
  • tags: любой набор значений ключей, которые можно использовать для поиска и фильтрации сертификатов.
import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

await client.beginCreateCertificate(certificateName, certificatePolicy, {
  enabled,
  tags,
});

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

// You can use the pending certificate immediately:
const pendingCertificate = poller.getResult();

// Or you can wait until the certificate finishes being signed:
const keyVaultCertificate = await poller.pollUntilDone();
console.log(keyVaultCertificate);

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

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

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The certificate ${certificateName} is fully created`);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

const latestCertificate = await client.getCertificate(certificateName);
console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
const specificCertificate = await client.getCertificateVersion(
  certificateName,
  latestCertificate.properties.version,
);
console.log(
  `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
  specificCertificate,
);

Получение полных сведений о сертификате

Дизайн Azure Key Vault чётко различает ключи, секреты и сертификаты. Функции Сертификатов сервиса Key Vault были разработаны с учётом возможностей Ключей и Секретов. Давайте оценим состав сертификата Key Vault:

Когда создаётся сертификат Key Vault, также создаются адресируемый ключ и секрет с одним именем. Ключ Key Vault позволяет выполнять операции с ключами, а секрет Key Vault позволяет получить значение сертификата как секрет. Сертификат Key Vault также содержит публичные метаданные сертификата x509. источник : составсертификата.

Зная, что приватный ключ хранится в Key Vault Secret с публичным сертификатом, мы можем получить его с помощью клиента Key Vault Secrets.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
writeFileSync("myCertificate.p12", PKCS12Certificate);

Обратите внимание, что по умолчанию тип контента сертификатов — PKCS 12. Указав тип контента сертификата, вы сможете получить его в формате PEM. Прежде чем показывать, как создавать сертификаты PEM, сначала рассмотрим, как получить секретный ключ PEM из сертификата PKCS 12.

Используя openssl, вы можете получить общедоступный сертификат в формате PEM с помощью следующей команды:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

Вы также можете использовать openssl для получения закрытого ключа следующим образом:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Обратите внимание, что в обоих случаях opensl запрашивает пароль, используемый для создания сертификата. Пример кода, который мы использовали до сих пор, не указал пароль, поэтому вы можете добавить -passin 'pass:' в конец каждой команды.

Сертификаты в формате PEM

Если вы хотите работать с сертификатами в формате PEM, вы можете поручить Azure сервису Key Vault создавать и управлять вашими сертификатами в формате PEM, указав свойство contentType в момент создания сертификатов.

Следующий пример показывает, как создать и получить публичную и частную части сертификата в формате PEM с помощью клиентов Key Vault for Certificates and Secrets:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Помните, что общедоступный сертификат будет находиться в том же большом двоичном объекте содержимого, что и закрытый ключ. Для их извлечения можно использовать заголовки PEM.

Вывод списка всех сертификатов

listPropertiesOfCertificates перечислит все сертификаты в Key Vault.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

Обновление сертификата

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = await client.getCertificate(certificateName);
await client.updateCertificateProperties(certificateName, result.properties.version, {
  enabled: false,
  tags: {
    myCustomTag: "myCustomTagsValue",
  },
});

Политика сертификата также может быть обновлена отдельно с помощью updateCertificatePolicyследующим образом:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = client.getCertificate(certificateName);
// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.updateCertificatePolicy(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const poller = await client.beginDeleteCertificate(certificateName);

// You can use the deleted certificate immediately:
const deletedCertificate = poller.getResult();

// The certificate 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 certificate this way:
await client.getDeletedCertificate(certificateName);

// Deleted certificates can also be recovered or purged.

// recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
// const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
// await recoverPoller.pollUntilDone();

// If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
await client.purgeDeletedCertificate(certificateName);

Так как удаление сертификата не произойдет мгновенно, некоторое время необходимо после вызова метода beginDeleteCertificate, прежде чем удаленный сертификат доступен для чтения, восстановления или очистки.

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

С помощью CertificateClient можно получить и выполнить итерацию по всем сертификатам в Хранилище сертификатов, а также через все удаленные сертификаты и версии определенного сертификата. Доступны следующие методы API:

  • listPropertiesOfCertificates перечислит все неудалённые сертификаты по их именам только в последних версиях.
  • listDeletedCertificates перечислит все удаленные сертификаты по их именам только в последних версиях.
  • listPropertiesOfCertificateVersions перечисляет все версии сертификата на основе имени сертификата.

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log("Certificate properties: ", certificateProperties);
  }
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
}
for await (const page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
  for (const certificateProperties of page) {
    console.log("Properties of certificate: ", certificateProperties);
  }
}

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

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

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

setLogLevel("info");

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

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

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

Способствует

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

  • Last updated on