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

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

Ресурсы клиентской библиотеки Key Vault:

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

Дополнительные сведения о Key Vault и сертификатах см. в следующих статьях:

Требования

Подписка Azure — создайте бесплатную учетную запись.
Текущая Node.js LTS.
Azure CLI
Существующее хранилище ключей — его можно создать с помощью:

Подписка Azure — создайте бесплатную учетную запись.
Текущая Node.js LTS.
TypeScript 5+
Azure CLI
Существующее хранилище ключей — его можно создать с помощью:

В этом кратком руководстве предполагается, что вы используете Azure CLI.

Выполните команду login.
```
az login
```
Если CLI может открыть ваш браузер по умолчанию, он откроет его и загрузит страницу входа в Azure.

В противном случае самостоятельно откройте в браузере страницу https://aka.ms/devicelogin и введите код авторизации, отображаемый в терминале.
Выполните вход в браузере с помощью учетных данных.

Создание приложения Node.js

Создайте приложение Node.js, использующее ваше хранилище ключей.

В терминале создайте папку с именем key-vault-node-app и перейдите в эту папку.
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Инициализация проекта Node.js:
```
npm init -y
```

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

С помощью терминала установите библиотеку секретов Azure Key Vault, @azure/keyvault-certificates для Node.js.
```
npm install @azure/keyvault-certificates
```
Установите библиотеку клиентских удостоверений Azure, @azure/identity, чтобы аутентифицироваться в Key Vault.
```
npm install @azure/identity
```

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

Чтобы получить разрешения для хранилища ключей с помощью контроль доступа на основе ролей (RBAC), назначьте роль для "User Principal Name" (UPN) с помощью команды az role assignment create.

az role assignment create --role "Key Vault Certificates Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/<vault-name>"

Замените <upn>, <subscription-id>а <vault-name> также фактическими значениями. Если вы использовали другое имя группы ресурсов, замените myResourceGroup. Ваше имя пользователя (UPN) обычно имеет формат адреса электронной почты, например username@domain.com.

Настройка переменных среды

Это приложение использует конечную точку хранилища ключей в качестве переменной окружения KEY_VAULT_URL.

set KEY_VAULT_URL=<key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<key-vault-endpoint>"

export KEY_VAULT_URL=<key-vault-endpoint>

Аутентификация и создание клиента

Запросы приложений к большинству служб Azure должны быть авторизованы. Использование метода DefaultAzureCredential, предоставленного библиотекой клиента идентификации Azure, является рекомендуемым подходом для реализации подключений к службам Azure без пароля в вашем коде. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

В этом кратком руководстве DefaultAzureCredential происходит аутентификация в хранилище ключей с использованием учетных данных пользователя-разработчика, подключенного к Azure CLI. При развертывании приложения в Azure тот же DefaultAzureCredential код может автоматически обнаруживать и использовать управляемое удостоверение, назначенное службе приложений, виртуальной машине или другим службам. Дополнительные сведения см. в разделе Обзор управляемых удостоверений.

В этом коде конечная точка вашего хранилища ключей используется для создания клиентского приложения хранилища ключей. Формат конечной точки, такой как https://<vault-name>.vault.azure.net, может изменяться для суверенных облаков. Дополнительные сведения о проверке подлинности в хранилище ключей см. в руководстве для разработчиков.

Пример кода

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

Настройка платформы приложения

Создайте новый текстовый файл и вставьте приведенный ниже код в файл index.js.

Замечание

Это краткое руководство создает самозаверенный сертификат в демонстрационных целях. Для рабочих нагрузок интегрируйте Key Vault с доверенным центром сертификации. См. раздел Защита сертификатов в Azure Key Vault.

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

async function main() {
  // DefaultAzureCredential automatically uses managed identity in Azure environments.
  // For local development, it uses credentials from Azure CLI, Azure PowerShell, or environment variables.
  // See: https://learn.microsoft.com/javascript/api/@azure/identity/defaultazurecredential
  const credential = new DefaultAzureCredential();

  const keyVaultUrl = process.env["KEY_VAULT_URL"];
  if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

  const client = new CertificateClient(keyVaultUrl, credential);

  const uniqueString = new Date().getTime();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  const pendingCertificate = createPoller.getResult();
  console.log("Certificate: ", pendingCertificate);

  // To read a certificate with their policy:
  let certificateWithPolicy = await client.getCertificate(certificateName);
  // Note: It will always read the latest version of the certificate.

  console.log("Certificate with policy:", certificateWithPolicy);

  // To read a certificate from a specific version:
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version
  );
  // Note: It will not retrieve the certificate's policy.
  console.log("Certificate from a specific version:", certificateFromVersion);

  const updatedCertificate = await client.updateCertificateProperties(certificateName, "", {
    tags: {
      customTag: "value"
    }
  });
  console.log("Updated certificate:", updatedCertificate);

  // Updating the certificate's policy:
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyOtherCert"
  });
  certificateWithPolicy = await client.getCertificate(certificateName);
  console.log("updatedCertificate certificate's policy:", certificateWithPolicy.policy);

  // delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  console.log("Recovery Id: ", deletedCertificate.recoveryId);
  console.log("Deleted Date: ", deletedCertificate.deletedOn);
  console.log("Scheduled Purge Date: ", deletedCertificate.scheduledPurgeDate);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Запуск примера приложения

Запустите приложение:
```
node index.js
```

Методы создания и получения возвращают полный объект JSON в сертификате:

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "<certificate-name>",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://<key-vault-name>.vault.azure.net/certificates/<certificate-name>/<certificate-version>",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "<certificate-name>",
    "vaultUrl": "https://<key-vault-name>.vault.azure.net",
    "version": "<certificate-version>",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Создайте текстовый файл и вставьте следующий код в файл index.ts .

import {
  CertificateClient,
  DefaultCertificatePolicy,
  KeyVaultCertificate,
  DeletedCertificate,
  CertificatePolicy,
  KeyVaultCertificateWithPolicy,
} from "@azure/keyvault-certificates";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

const credential = new DefaultAzureCredential();

// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

function printCertificate(
  certificate: KeyVaultCertificate | KeyVaultCertificateWithPolicy
): void {
  console.log("-- printCertificate ---------------------------");

  // if policy is defined, it's a KeyVaultCertificateWithPolicy
  if ((certificate as KeyVaultCertificateWithPolicy).policy) {
    const { name, properties, policy } =
      certificate as KeyVaultCertificateWithPolicy;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    console.log("Certificate Policy: ", policy);
    printObjectProperties(tags);
    return;
  } else {
    const { name, properties } = certificate;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    printObjectProperties(tags);
  }
}
// Object properties are tags and CertificatePolicy
function printObjectProperties(obj: Record<string, any>): void {
  if (!obj) return;

  console.log("-- printObjectProperties ---------------------------");

  Object.entries(obj).forEach(([key, value]) => {
    if (key === "lifetimeActions") {
      console.log(`${key}: ${JSON.stringify(value)}`);
    } else {
      console.log(`${key}: ${value}`);
    }
  });
}
function printDeletedCertificate(deletedCertificate: DeletedCertificate): void {
  const { recoveryId, deletedOn, scheduledPurgeDate } = deletedCertificate;
  console.log("Deleted Certificate: ", {
    recoveryId,
    deletedOn,
    scheduledPurgeDate,
  });
}
async function main(): Promise<void> {
  // Create a new CertificateClient
  const client = new CertificateClient(keyVaultUrl, credential);

  // Create a unique certificate name
  const uniqueString = new Date().getTime().toString();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  // Get the created certificate
  const pendingCertificate = await createPoller.getResult();
  printCertificate(pendingCertificate);

  // Get certificate by name
  let certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(pendingCertificate);

  // Get certificate by version
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version!
  );
  printCertificate(certificateFromVersion);

  // Update properties of the certificate
  const updatedCertificate = await client.updateCertificateProperties(
    certificateName,
    certificateWithPolicy.properties.version!,
    {
      tags: {
        customTag: "my value",
      },
    }
  );
  printCertificate(updatedCertificate);

  // Updating the certificate's policy
  const certificatePolicy = await client.updateCertificatePolicy(
    certificateName,
    {
      issuerName: "Self",
      subject: "cn=MyOtherCert",
    }
  );
  printObjectProperties(certificatePolicy);

  // Get certificate again to see the updated policy
  certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(certificateWithPolicy);

  // Delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  printDeletedCertificate(deletedCertificate);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Запуск примера приложения

Создайте приложение TypeScript:
```
tsc
```
Запустите приложение:
```
node index.js
```

Методы создания и получения возвращают полный объект JSON в сертификате:

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "<certificate-name>",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://<key-vault-name>.vault.azure.net/certificates/<certificate-name>/<certificate-version>",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "<certificate-name>",
    "vaultUrl": "https://<key-vault-name>.vault.azure.net",
    "version": "<certificate-version>",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Интеграция со службой "Конфигурация приложений"

Пакет SDK Azure предоставляет вспомогательный метод «parseKeyVaultCertificateIdentifier», чтобы проанализировать указанный идентификатор сертификата Key Vault, который необходим при использовании ссылок на Key Vault в «App Configuration». В конфигурации приложений хранится идентификатор сертификата Key Vault. Чтобы получить имя сертификата, необходимо выполнить анализ этого идентификатора с помощью метода parseKeyVaultCertificateIdentifier. После получения имени сертификата, можно получить текущий сертификат, используя код из этого краткого руководства.

Следующие шаги

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-12

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

Требования

Вход в Azure

Создание приложения Node.js

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

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

Настройка переменных среды

Аутентификация и создание клиента

Пример кода

Настройка платформы приложения

Запуск примера приложения

Запуск примера приложения

Интеграция со службой "Конфигурация приложений"

Следующие шаги

Обратная связь

Дополнительные ресурсы