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

Статья
10/17/2024

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

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

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

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

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

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

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

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

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

версии LTS Node.js

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

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

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

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

npm install @azure/keyvault-certificates

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

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

npm install @azure/identity

Настройка TypeScript

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

npm install @types/node

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

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

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

Чтобы взаимодействовать со службой Azure Key Vault, необходимо создать экземпляр класса , 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);

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

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

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

По умолчанию этот пакет использует последнюю версию службы Azure Key Vault, которая 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 создает сертификат для хранения в Azure 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() {
  // 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

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

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

Если вы хотите работать с сертификатами в формате PEM, вы можете сообщить службе Azure Key Vault создать сертификаты и управлять ими в формате 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

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

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

впечатлений

Поделиться через