Inicio rápido: Biblioteca cliente de claves de Azure Key Vault para JavaScript

Artículo
04/09/2024

Comience a trabajar con la biblioteca cliente de Azure Key Vault para JavaScript. Azure Key Vault es un servicio en la nube que ofrece el almacenamiento seguro de las claves criptográficas. Puede almacenar de forma segura claves, contraseñas, certificados y otros secretos. Las instancias de Azure Key Vault se pueden crear y administrar a través de Azure Portal. En este inicio rápido, aprenderá a crear, recuperar y eliminar secretos de una instancia de Azure Key Vault mediante la biblioteca cliente de claves de JavaScript.

Recursos de la biblioteca cliente de Key Vault:

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (npm)

Para más información sobre Key Vault y las claves, consulte:

Requisitos previos

Una suscripción a Azure: cree una cuenta gratuita.
Node.js LTS actual.
CLI de Azure
Un almacén de claves existente: puede crear uno con:

En este inicio rápido, se da por supuesto que ejecuta la CLI de Azure.

Ejecute el comando login.
```
az login
```
Si la CLI puede abrir el explorador predeterminado, lo hará y cargará una página de inicio de sesión de Azure.

En caso contrario, abra una página del explorador en https://aka.ms/devicelogin y escriba el código de autorización que se muestra en el terminal.
Inicie sesión con las credenciales de su cuenta en el explorador.

Creación de una aplicación de Node.js

Cree una aplicación Node.js que use el almacén de claves.

En un terminal, cree una carpeta con el nombre key-vault-node-app y cámbiela a esa carpeta:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Inicialice el proyecto de Node.js:
```
npm init -y
```

Instalación de paquetes de Key Vault

Con el terminal, instale la biblioteca cliente de secretos de Azure Key Vault, @azure/keyvault-keys para Node.js.
```
npm install @azure/keyvault-keys
```
Instale la biblioteca cliente de identidades de Azure, @azure/identity para autenticarse en un almacén de claves.
```
npm install @azure/identity
```

Para conceder permisos de aplicación al almacén de claves a través del control de acceso basado en rol (RBAC), asigne un rol mediante el comando de la CLI de Azure crear la asignación de roles.

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>"

Para conceder permisos de aplicación al almacén de claves mediante el control de acceso basado en rol (RBAC), asigne un rol mediante el cmdlet New-AzRoleAssignment de Azure PowerShell.

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>"

Reemplace <app-id>, <suscripción-id>, <resource-group-name> y <your-unique-keyvault-name> por los valores reales. <app-id> es el identificador de aplicación (cliente) de la aplicación registrada en Azure AD.

Establecimiento de variables de entorno

Esta aplicación también usa el nombre del almacén de claves como variable de entorno llamada 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>

Autenticación y creación de un cliente

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. El uso del método DefaultAzureCredential que proporciona la biblioteca cliente de Azure Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

En este inicio rápido, DefaultAzureCredential se autentica en el almacén de claves mediante las credenciales del usuario de desarrollo local que inició sesión en la CLI de Azure. Cuando la aplicación se implementa en Azure, el mismo código DefaultAzureCredential puede detectar y usar automáticamente una identidad administrada asignada a una instancia de App Service, máquina virtual u otros servicios. Para más información, consulte Introducción a la identidad administrada.

En este código, el nombre del almacén de claves se utiliza para crear el URI del almacén de claves, con el formato https://<your-key-vault-name>.vault.azure.net. Para más información sobre la autenticación en el almacén de claves, consulte la Guía del desarrollador.

Ejemplo de código

Los ejemplos de código siguientes le mostrarán cómo crear un cliente y cómo establecer, recuperar y eliminar un secreto.

Este código usa las siguientes clases y métodos secretos de Key Vault:

Instalación del marco de la aplicación

Cree un nuevo archivo de texto y pegue el siguiente código en el archivo 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);
});

Ejecutar la aplicación de ejemplo

Ejecute la aplicación:
```
node index.js
```

Los métodos crear y obtener devuelven un objeto JSON completo para la clave:

"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"
  }
}

Integración con App Configuration

El SDK de Azure proporciona un método auxiliar, parseKeyVaultKeyIdentifier, para analizar el identificador de secreto de Key Vault determinado. Esto es necesario si usa referencias de App Configuration en Key Vault. App Config almacena el id. de clave de Key Vault. Necesita el método parseKeyVaultKeyIdentifier para analizar ese identificador para obtener el nombre clave. Una vez que tenga el nombre clave, puede obtener el valor clave actual con código de esta guía de inicio rápido.

Pasos siguientes

En este inicio rápido, ha creado un almacén de claves y ha almacenado una clave y recuperado dicha clave. Para más información sobre Key Vault y cómo integrarlo con las aplicaciones, vaya a estos artículos.

Lea una introducción a Azure Key Vault.
Lea una introducción a las claves de Azure Key Vault
Procedimientos para proteger el acceso a un almacén de claves
Consulte la guía del desarrollador de Azure Key Vault.
Consulte Introducción a la seguridad de Azure Key Vault