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

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

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

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

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

• Общие сведения о Key Vault
• Общие сведения о ключах.

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

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

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

Вход в Azure

1. Выполните команду login.

   az login
   

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

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

2. Выполните вход в браузере с помощью учетных данных.

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

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

1. В терминале создайте папку с именем key-vault-node-app и измените в этой папке:

   mkdir key-vault-node-app && cd key-vault-node-app
   

2. Инициализация проекта Node.js:

   npm init -y
   

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

1. С помощью терминала установите клиентская библиотека секретов Azure Key Vault, @azure/keyvault-keys для Node.js.

   npm install @azure/keyvault-keys
   

2. Установите клиентская библиотека удостоверений Azure, @azure/пакет удостоверений для проверки подлинности в Key Vault.

   npm install @azure/identity
   

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

Azure CLI

Чтобы предоставить приложению разрешения для хранилища ключей с помощью контроль доступа на основе ролей (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>"

Azure PowerShell

Чтобы предоставить приложению разрешения для хранилища ключей с помощью контроль доступа на основе ролей (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.

Windows

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

PowerShell

Windows PowerShell

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

macOS или Linux

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:

• Класс DefaultAzureCredential
• Класс KeyClient
  • Createkey
  • createEcKey
  • createRsaKey
  • getKey
  • listPropertiesOfKeys
  • updateKeyProperties
  • beginDeleteKey
  • getDeletedKey
  • ОчисткаDeletedKey

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

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

   const { KeyClient } = require("@azure/keyvault-keys");
   const { DefaultAzureCredential } = require("@azure/identity");
   
   async function main() {
   
       // 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 KeyClient(url, credential);
   
       const uniqueString = Date.now();
       const keyName = `sample-key-${uniqueString}`;
       const ecKeyName = `sample-ec-key-${uniqueString}`;
       const rsaKeyName = `sample-rsa-key-${uniqueString}`;
   
       // Create key using the general method
       const result = await client.createKey(keyName, "EC");
       console.log("key: ", result);
   
       // Create key using specialized key creation methods
       const ecResult = await client.createEcKey(ecKeyName, { curve: "P-256" });
       const rsaResult = await client.createRsaKey(rsaKeyName, { keySize: 2048 });
       console.log("Elliptic curve key: ", ecResult);
       console.log("RSA Key: ", rsaResult);
   
       // Get a specific key
       const key = await client.getKey(keyName);
       console.log("key: ", key);
   
       // Or list the keys we have
       for await (const keyProperties of client.listPropertiesOfKeys()) {
       const key = await client.getKey(keyProperties.name);
       console.log("key: ", key);
       }
   
       // Update the key
       const updatedKey = await client.updateKeyProperties(keyName, result.properties.version, {
       enabled: false
       });
       console.log("updated key: ", updatedKey);
   
       // Delete the key - the key is soft-deleted but not yet purged
       const deletePoller = await client.beginDeleteKey(keyName);
       await deletePoller.pollUntilDone();
   
       const deletedKey = await client.getDeletedKey(keyName);
       console.log("deleted key: ", deletedKey);
   
       // Purge the key - the key is permanently deleted
       // This operation could take some time to complete
       console.time("purge a single key");
       await client.purgeDeletedKey(keyName);
       console.timeEnd("purge a single key");
   }
   
   main().catch((error) => {
     console.error("An error occurred:", error);
     process.exit(1);
   });
   

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

1. Запустите приложение:

   node index.js
   

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

   "key":  {
     "key": {
       "kid": "https://YOUR-KEY-VAULT-NAME.vault.azure.net/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
       "kty": "YOUR-KEY-TYPE",
       "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
       ... other properties based on key type
     },
     "id": "https://YOUR-KEY-VAULT-NAME.vault.azure.net/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
     "name": "YOUR-KEY-NAME",
     "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
     "keyType": "YOUR-KEY-TYPE",
     "properties": {
       "tags": undefined,
       "enabled": true,
       "notBefore": undefined,
       "expiresOn": undefined,
       "createdOn": 2021-11-29T18:29:11.000Z,
       "updatedOn": 2021-11-29T18:29:11.000Z,
       "recoverableDays": 90,
       "recoveryLevel": "Recoverable+Purgeable",
       "exportable": undefined,
       "releasePolicy": undefined,
       "vaultUrl": "https://YOUR-KEY-VAULT-NAME.vault.azure.net",
       "version": "YOUR-KEY-VERSION",
       "name": "YOUR-KEY-VAULT-NAME",
       "managed": undefined,
       "id": "https://YOUR-KEY-VAULT-NAME.vault.azure.net/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
     }
   }
   

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

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

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

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

• Обзор Azure Key Vault
• Обзор ключей Azure Key Vault
• Безопасный доступ к хранилищу ключей
• Руководство разработчика Azure Key Vault
• Статья Обзор системы безопасности Key Vault