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

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

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

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

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

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

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

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

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

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

• LTS версии Node.js

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

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

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

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

npm install @azure/keyvault-certificates

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

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

npm install @azure/identity

Настройка TypeScript

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

npm install @types/node

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

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

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

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

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

Вот краткий пример. Сначала импортируйте DefaultAzureCredential и CertificateClient:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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. После инициализации он предоставляет базовый набор методов, которые можно использовать для создания, чтения, обновления и удаления сертификатов.
• Версия сертификата — это версия сертификата в Key Vault. Каждый раз, когда пользователь присваивает значение уникальному имени сертификата, создается новая версия этого сертификата. При получении сертификата по имени всегда будет возвращено последнее назначенное значение, если в запросе не указана определенная версия.
• Обратимое удаление позволяет Key Vault поддерживать удаление и очистку в виде двух отдельных шагов, поэтому удаленные сертификаты не теряются сразу. Это происходит, только если в Key Vault включено обратимое удаление.
• Резервную копию сертификата можно создать из любого созданного сертификата. Эти резервные копии поступают в виде двоичных данных и могут использоваться только для повторного создания ранее удаленного сертификата.

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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.0",
});

Примеры

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

• Создание и настройка сертификата.
• Получение сертификата Key Vault.
• Получение полных сведений о сертификате.
• Сертификаты в формате PEM.
• Вывод списка всех сертификатов.
• Обновление сертификата.
• Удаление сертификата.
• Итерации списков сертификатов.

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  // 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",
  });
}

main();

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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",
};

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

main();

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

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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",
};

async function main() {
  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);
}

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
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 CertificateClient(url, credential);

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

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

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

main();

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  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
  );
}

main();

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

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

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

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

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// 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:
fs.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

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

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

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

В следующем примере показано, как создать и извлечь открытую и частную части сертификата в формате PEM с помощью клиентов Key Vault для сертификатов и секретов:

// 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.
});
const keyVaultCertificate = 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.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  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",
  });
}

main();

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

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  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);
}

main();

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

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

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

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

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

main();

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

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

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

setLogLevel("info");

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

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

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

• Примеры сертификатов Key Vault (JavaScript)
• Примеры сертификатов Key Vault (TypeScript)
• Тестовые случаи сертификатов Key Vault

Участие

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