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

Статья
04/08/2024

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

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

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

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

Необходимые компоненты

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

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

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

В противном случае самостоятельно откройте в браузере страницу 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
```

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

Azure CLI
Azure PowerShell

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

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Чтобы предоставить приложению разрешения для хранилища ключей с помощью контроль доступа на основе ролей (RBAC), назначьте роль с помощью командлета Azure PowerShell New-AzRoleAssignment.

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Замените app-id>, subscription-id>, <<resource-group-name и <your-unique-keyvault-name>> фактическими значениями.< <Идентификатор приложения — это идентификатор> приложения (клиента) зарегистрированного приложения в Azure AD.

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

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

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

export KEY_VAULT_NAME=<your-key-vault-name>

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

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

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

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

Пример кода

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

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

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

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

async function main() {
  // If you're using MSI, DefaultAzureCredential should "just work".
  // Otherwise, DefaultAzureCredential expects the following three environment variables:
  // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
  // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
  // - AZURE_CLIENT_SECRET: The client secret for the registered application
  const credential = new DefaultAzureCredential();

  const keyVaultName = process.env["KEY_VAULT_NAME"];
  if(!keyVaultName) throw new Error("KEY_VAULT_NAME is empty");
  const url = "https://" + keyVaultName + ".vault.azure.net";

  const client = new CertificateClient(url, 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": "YOUR-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://YOUR-KEY-VAULT-NAME.vault.azure.net/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME.vault.azure.net",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

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

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

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

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