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

Artículo
10/05/2024

Empiece a trabajar con la biblioteca cliente de certificados de Azure Key Vault para JavaScript. Azure Key Vault es un servicio en la nube que proporciona un almacén seguro para los certificados. 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 certificados de una instancia de Azure Key Vault mediante la biblioteca cliente 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 los certificados, consulte:

Prerrequisitos

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:

Una suscripción a Azure: cree una cuenta gratuita.
Node.js LTS actual.
TypeScript 5+
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 de secretos de Azure Key Vault, @azure/keyvault-certificates para Node.js.
```
npm install @azure/keyvault-certificates
```
Instale la biblioteca cliente de identidades de Azure, @azure/identity para autenticarse en un almacén de claves.
```
npm install @azure/identity
```

Concesión de acceso al almacén de claves

Para obtener permisos para el almacén de claves mediante Control de acceso basado en roles (RBAC), asigne un rol a su "Nombre principal de usuario" (UPN) mediante el comando de la CLI de Azure az role assignment create.

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

Reemplace <upn>, <subscription-id>, <resource-group-name> y <your-unique-keyvault-name> por los valores reales. El UPN normalmente tendrá el formato de una dirección de correo electrónico (por ejemplo, username@domain.com).

Establecimiento de variables de entorno

Esta aplicación también usa el punto de conexión del almacén de claves como variable de entorno llamada KEY_VAULT_URL.

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

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

export KEY_VAULT_URL=<your-key-vault-endpoint>

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 punto de conexión del almacén de claves se usa para crear el cliente del almacén de claves. El formato del punto de conexión es similar a https://<your-key-vault-name>.vault.azure.net, pero puede cambiar para nubes soberanas. 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

Este código usa las siguientes clases y métodos de certificados 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 { 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 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);
});

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 el certificado:

{
  "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-ENDPOINT/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-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

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

Ejecutar la aplicación de ejemplo

Compilar la aplicación TypeScript:
```
tsc
```
Ejecute la aplicación:
```
node index.js
```

Los métodos crear y obtener devuelven un objeto JSON completo para el certificado:

{
  "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-ENDPOINT/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-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Integración con App Configuration

El SDK de Azure proporciona un método auxiliar, parseKeyVaultCertificateIdentifier, para analizar el identificador de certificado de Key Vault dado, que es necesario si usa referencias de App Configuration a Key Vault. App Config almacena el identificador de certificado de Key Vault. Necesita el método parseKeyVaultCertificateIdentifier para analizar ese identificador para obtener el nombre del certificado. Una vez que tenga el nombre del certificado, puede obtener el certificado actual con el código de este inicio rápido.

Pasos siguientes

En este inicio rápido, ha creado un almacén de claves, ha almacenado un certificado y, posteriormente, lo ha recuperado. 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 los certificados.
Vea un Tutorial sobre el acceso a Key Vault desde una aplicación de App Service.
Consulte un Tutorial sobre el acceso a Key Vault desde una máquina virtual.
Consulte la guía del desarrollador de Azure Key Vault.
Consulte Introducción a la seguridad de Azure Key Vault

Compartir vía

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

Prerrequisitos

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

Instalación de paquetes de Key Vault

Concesión de acceso al almacén de claves

Establecimiento de variables de entorno

Autenticación y creación de un cliente

Ejemplo de código

Instalación del marco de la aplicación

Ejecutar la aplicación de ejemplo

Ejecutar la aplicación de ejemplo

Integración con App Configuration

Pasos siguientes

Comentarios

Recursos adicionales

Compartir vía

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

Prerrequisitos

Inicio de sesión en Azure

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

Instalación de paquetes de Key Vault

Concesión de acceso al almacén de claves

Establecimiento de variables de entorno

Autenticación y creación de un cliente

Ejemplo de código

Instalación del marco de la aplicación

Ejecutar la aplicación de ejemplo

Ejecutar la aplicación de ejemplo

Integración con App Configuration

Pasos siguientes

Comentarios

Recursos adicionales