Azure Key Vault Certificates biblioteca cliente para JavaScript - versión 4.10.3

Azure Key Vault es un servicio en la nube que proporciona almacenamiento seguro y gestión automatizada de certificados utilizados en toda una aplicación en la nube. Múltiples certificados y múltiples versiones del mismo certificado pueden mantenerse en Azure Key Vault. Cada certificado del almacén tiene una directiva asociada a él que controla la emisión y duración del certificado, junto con las acciones que se deben realizar a medida que los certificados expiran.

Si quieres saber más sobre Azure Key Vault, quizá quieras revisar: ¿Qué es Azure Key Vault?

Utiliza la biblioteca cliente para Azure Key Vault Certificados en tu Node.js solicitud para:

  • Obtiene, establece y elimina un certificado.
  • Actualice un certificado, sus atributos, emisor, directiva, operación y contactos.
  • Copia de seguridad y restauración de un certificado.
  • Obtenga, purgue o recupere un certificado eliminado.
  • Obtenga todas las versiones de un certificado.
  • Obtenga todos los certificados.
  • Obtenga todos los certificados eliminados.

Nota: Este paquete no puede usarse en el navegador debido a limitaciones de Azure Key Vault servicio; por favor, consulte este documento para obtener orientación.

Vínculos clave:

Empezar

Entornos admitidos actualmente

Prerrequisitos

  • Una suscripción Azure
  • Un Azure Key Vault existente. Si necesitas crear una bóveda de llaves, puedes hacerlo en el Azure Portal siguiendo los pasos de este documento. Alternativamente, utiliza el CLI de Azure siguiendo estos pasos.

Instalación del paquete

Instala la biblioteca cliente de Azure Key Vault Certificates usando npm

npm install @azure/keyvault-certificates

Instalación de la biblioteca de identidades

Los clientes de Key Vault se autentican usando la Biblioteca de Identidad de Azure. Instálelo también mediante npm

npm install @azure/identity

Configurar TypeScript

Los usuarios de TypeScript deben tener instaladas definiciones de tipo de nodo:

npm install @types/node

También debe habilitar compilerOptions.allowSyntheticDefaultImports en el tsconfig.json. Tenga en cuenta que si ha habilitado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está habilitado de forma predeterminada. Consulte manual de opciones del compilador de TypeScript para obtener más información.

Autenticación con Azure Active Directory

El servicio Key Vault depende de Azure Active Directory para autenticar las solicitudes a sus APIs. El paquete @azure/identity proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. El README para @azure/identity ofrece más detalles y muestras para que empieces.

Para interactuar con el servicio Azure Key Vault, necesitarás crear una instancia de la clase CertificateClient, una URL vault y un objeto de credencial. Los ejemplos que se muestran en este documento usan un objeto de credencial denominado DefaultAzureCredential, que es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales. Además, se recomienda usar una identidad administrada para la autenticación en entornos de producción.

Puedes encontrar más información sobre las diferentes formas de autenticación y sus tipos de credenciales correspondientes en la Azure Documentación de Identidad.

Este es un ejemplo rápido. En primer lugar, importe DefaultAzureCredential y CertificateClient. Una vez importados, podemos conectarse al servicio key vault:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our certificates client and connect to the service
const client = new CertificateClient(url, credential);

Conceptos clave

  • El cliente Certificates es la interfaz principal para interactuar con los métodos API relacionados con los certificados en la API Azure Key Vault desde una aplicación JavaScript. Una vez inicializado, proporciona un conjunto básico de métodos que se pueden usar para crear, leer, actualizar y eliminar certificados.
  • Una versión Certificate es una versión de un certificado en el Key Vault. Cada vez que un usuario asigna un valor a un nombre de certificado único, se crea una nueva versión de de ese certificado. La recuperación de un certificado por un nombre siempre devolverá el valor más reciente asignado, a menos que se proporcione una versión específica a la consulta.
  • eliminación temporal permite que key Vault admita la eliminación y purga como dos pasos independientes, por lo que los certificados eliminados no se pierden inmediatamente. Esto solo ocurre si el Key Vault tiene activado soft-delete.
  • Se puede generar un de copia de seguridad de certificados a partir de cualquier certificado creado. Estas copias de seguridad se incluyen como datos binarios y solo se pueden usar para regenerar un certificado eliminado previamente.

Especificar la versión de la API del servicio Azure Key Vault

Por defecto, este paquete utiliza la última versión de Azure Key Vault service, que es 7.1. La única versión compatible es 7.0. Puede cambiar la versión del servicio que se usa estableciendo la opción serviceVersion en el constructor de cliente, como se muestra a continuación:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new CertificateClient(url, credential, {
  serviceVersion: "7.5",
});

Ejemplos

Las siguientes secciones proporcionan fragmentos de código que cubren algunas de las tareas comunes que utilizan los certificados de Azure Key Vault. Los escenarios que se tratan aquí constan de:

Creación y configuración de un certificado

beginCreateCertificate crea un certificado que se almacena en el Azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

Además del nombre del certificado y la directiva, también puede pasar las siguientes propiedades en un tercer argumento con valores opcionales:

  • enabled: valor booleano que determina si el certificado se puede usar o no.
  • tags: cualquier conjunto de valores de clave que se pueden usar para buscar y filtrar certificados.
import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

await client.beginCreateCertificate(certificateName, certificatePolicy, {
  enabled,
  tags,
});

Al llamar a beginCreateCertificate con el mismo nombre, se creará una nueva versión del mismo certificado, que tendrá los atributos proporcionados más recientes.

Dado que los certificados tardan algún tiempo en crearse completamente, beginCreateCertificate devuelve un objeto de sondeo que realiza un seguimiento de la operación de larga duración subyacente según nuestras directrices: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

El sondeo recibido le permitirá obtener el certificado creado llamando a poller.getResult(). También puede esperar hasta que finalice la eliminación, ya sea ejecutando llamadas de servicio individuales hasta que se cree el certificado o esperando hasta que finalice el proceso:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

// You can use the pending certificate immediately:
const pendingCertificate = poller.getResult();

// Or you can wait until the certificate finishes being signed:
const keyVaultCertificate = await poller.pollUntilDone();
console.log(keyVaultCertificate);

Otra manera de esperar hasta que se firma el certificado es realizar llamadas individuales, como se indica a continuación:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The certificate ${certificateName} is fully created`);

Obtener un certificado de Key Vault

La manera más sencilla de leer certificados desde el almacén es obtener un certificado por nombre. getCertificate recuperará la versión más reciente del certificado, junto con la directiva del certificado. Opcionalmente, puede obtener una versión diferente del certificado llamando a getCertificateVersion si especifica la versión. getCertificateVersion no devuelve la directiva del certificado.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

const latestCertificate = await client.getCertificate(certificateName);
console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
const specificCertificate = await client.getCertificateVersion(
  certificateName,
  latestCertificate.properties.version,
);
console.log(
  `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
  specificCertificate,
);

Obtención de la información completa de un certificado

El diseño de Azure Key Vault hace distinciones claras entre Llaves, Secretos y Certificados. Las funciones de Certificados del servicio Key Vault fueron diseñadas aprovechando sus capacidades de Llaves y Secretos. Vamos a evaluar la composición de un Certificado Key Vault:

Cuando se crea un certificado Key Vault, también se crean una clave direccionable y un secreto con el mismo nombre. La clave Key Vault permite operaciones con claves y el Key Vault secret permite recuperar el valor del certificado como secreto. Un certificado de Key Vault también contiene metadatos públicos de certificados x509. Origen: Composición de un certificado.

Sabiendo que la clave privada está almacenada en un Key Vault Secret, con el certificado público incluido, podemos recuperarla usando el cliente Key Vault Secrets.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
writeFileSync("myCertificate.p12", PKCS12Certificate);

Tenga en cuenta que, de forma predeterminada, el tipo de contenido de los certificados es PKCS 12. Al especificar el tipo de contenido del certificado, podrá recuperarlo en formato PEM. Antes de mostrar cómo crear certificados PEM, primero vamos a explorar cómo recuperar una clave secreta PEM de un certificado PKCS 12 primero.

Con openssl, puede recuperar el certificado público en formato PEM mediante el siguiente comando:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

También puede usar openssl para recuperar la clave privada, como se indica a continuación:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Tenga en cuenta que, en ambos casos, openssl le pedirá la contraseña usada para crear el certificado. El código de ejemplo que hemos usado hasta ahora no ha especificado una contraseña, por lo que puede anexar -passin 'pass:' al final de cada comando.

Certificados en formato PEM

Si quieres trabajar con certificados en formato PEM, puedes pedir al servicio Key Vault de Azure que cree y gestione tus certificados en formato PEM proporcionando la propiedad contentType en el momento de crear los certificados.

El siguiente ejemplo muestra cómo crear y recuperar las partes públicas y privadas de un certificado con formato PEM utilizando los clientes Key Vault para Certificados y Secretos:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Tenga en cuenta que el certificado público estará en el mismo blob de contenido que la clave privada. Puede usar los encabezados PEM para extraerlos en consecuencia.

Enumerar todos los certificados

listPropertiesOfCertificates listará todos los certificados en el Key Vault.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

Actualización de un certificado

Los atributos de certificado se pueden actualizar a una versión de certificado existente con updateCertificate, como se indica a continuación:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = await client.getCertificate(certificateName);
await client.updateCertificateProperties(certificateName, result.properties.version, {
  enabled: false,
  tags: {
    myCustomTag: "myCustomTagsValue",
  },
});

La directiva del certificado también se puede actualizar individualmente con updateCertificatePolicy, como se indica a continuación:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = client.getCertificate(certificateName);
// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.updateCertificatePolicy(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

Eliminación de un certificado

El método beginDeleteCertificate configura un certificado para su eliminación. Este proceso se producirá en segundo plano en cuanto estén disponibles los recursos necesarios.

Si soft-delete está habilitado para el Key Vault, esta operación solo etiquetará el certificado como un certificado eliminado. No se puede actualizar un certificado eliminado. Solo se pueden leer, recuperar o purgar.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const poller = await client.beginDeleteCertificate(certificateName);

// You can use the deleted certificate immediately:
const deletedCertificate = poller.getResult();

// The certificate is being deleted. Only wait for it if you want to restore it or purge it.
await poller.pollUntilDone();

// You can also get the deleted certificate this way:
await client.getDeletedCertificate(certificateName);

// Deleted certificates can also be recovered or purged.

// recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
// const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
// await recoverPoller.pollUntilDone();

// If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
await client.purgeDeletedCertificate(certificateName);

Dado que la eliminación de un certificado no se producirá al instante, se necesita algún tiempo después de llamar al método beginDeleteCertificate antes de que el certificado eliminado esté disponible para ser leído, recuperado o purgado.

Iteración de listas de certificados

Con CertificateClient, puede recuperar e iterar todos los certificados de un almacén de certificados, así como a través de todos los certificados eliminados y las versiones de un certificado específico. Los siguientes métodos de API están disponibles:

  • listPropertiesOfCertificates enumerará todos los certificados no eliminados por sus nombres, solo en sus versiones más recientes.
  • listDeletedCertificates enumerará todos los certificados eliminados por sus nombres, solo en sus versiones más recientes.
  • listPropertiesOfCertificateVersions enumerará todas las versiones de un certificado en función de un nombre de certificado.

Que se puede usar de la manera siguiente:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

Todos estos métodos devolverán todos los resultados disponibles a la vez. Para recuperarlos por páginas, agregue .byPage() justo después de invocar el método de API que desea usar, como se indica a continuación:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log("Certificate properties: ", certificateProperties);
  }
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
}
for await (const page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
  for (const certificateProperties of page) {
    console.log("Properties of certificate: ", certificateProperties);
  }
}

Solución de problemas

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Consulta nuestra guía solución de problemas para detalles sobre cómo diagnosticar distintos escenarios de fallo.

Pasos siguientes

Puede encontrar más ejemplos de código a través de los vínculos siguientes:

Contribuyendo

Si quieres contribuir a esta biblioteca, por favor lee la guía contribución para aprender más sobre cómo construir y probar el código.

  • Last updated on