Biblioteca cliente de certificados de Azure Key Vault para JavaScript: versión 4.8.0

  • Artículo

Azure Key Vault es un servicio en la nube que proporciona almacenamiento seguro y administración automatizada de certificados usados en una aplicación en la nube. Se pueden conservar varios certificados y varias versiones del mismo certificado en azure Key Vault. Cada certificado del almacén tiene una directiva asociada que controla la emisión y duración del certificado, junto con las acciones que se deben realizar a medida que los certificados están a punto de expirar.

Si desea obtener más información sobre Azure Key Vault, puede que desee revisar: ¿Qué es Azure Key Vault?

Use la biblioteca cliente para certificados de Azure Key Vault en la aplicación de Node.js para:

  • Obtiene, establece y elimina un certificado.
  • Actualice un certificado, sus atributos, emisor, directiva, operación y contactos.
  • Realice una copia de seguridad y restaure un certificado.
  • Obtener, purgar o recuperar un certificado eliminado.
  • Obtenga todas las versiones de un certificado.
  • Obtenga todos los certificados.
  • Obtiene todos los certificados eliminados.

Nota: Este paquete no se puede usar en el explorador debido a las limitaciones del servicio azure Key Vault, consulte este documento para obtener instrucciones.

Vínculos principales:

Introducción

Entornos admitidos actualmente

Requisitos previos

Instalar el paquete

Instalación de la biblioteca cliente de certificados de Azure Key Vault mediante npm

npm install @azure/keyvault-certificates

Instalación de la biblioteca de identidades

Key Vault los clientes se autentican mediante la biblioteca de identidades de Azure. Instálelo también con 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 la tsconfig.json. Tenga en cuenta que si ha habilitado , allowSyntheticDefaultImports está habilitado compilerOptions.esModuleInteropde forma predeterminada. Consulte el manual de opciones del compilador de TypeScript para obtener más información.

Autenticación con Azure Active Directory

El servicio Key Vault se basa en Azure Active Directory para autenticar las solicitudes en sus API. El paquete @azure/identity proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. El archivo Léame para @azure/identity proporciona más detalles y ejemplos para empezar.

Para interactuar con el servicio azure Key Vault, deberá crear una instancia de la CertificateClient clase, una dirección URL del almacén 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.

Puede encontrar más información sobre las distintas formas de autenticación y sus tipos de credenciales correspondientes en la documentación de Azure Identity.

Este es un ejemplo rápido. En primer lugar, importe DefaultAzureCredential y CertificateClient:

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

Una vez importados, podemos conectarse al servicio del almacén de claves:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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 de certificados es la interfaz principal para interactuar con los métodos de API relacionados con los certificados de la API de 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 del certificado 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 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.
  • La eliminación temporal permite a los almacenes de claves admitir la eliminación y purga como dos pasos independientes, por lo que los certificados eliminados no se pierden inmediatamente. Esto solo sucede si el Key Vault tiene habilitada la eliminación temporal.
  • Se puede generar una copia de seguridad de certificados a partir de cualquier certificado creado. Estas copias de seguridad vienen como datos binarios y solo se pueden usar para regenerar un certificado eliminado previamente.

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

De forma predeterminada, este paquete usa la versión más reciente del servicio azure Key Vault, que es 7.1. La única versión que se admite 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:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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.0",
});

Ejemplos

En las secciones siguientes se proporcionan fragmentos de código que abarcan algunas de las tareas comunes mediante Certificados de Azure Key Vault. Los escenarios que se tratan aquí constan de:

Creación y configuración de un certificado

beginCreateCertificatecrea un certificado que se va a almacenar en azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  // 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",
  });
}

main();

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 puede usar para buscar y filtrar certificados.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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",
};

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

main();

Al llamar a con beginCreateCertificate 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 por completo, beginCreateCertificate devuelve un objeto de sondeo que realiza un seguimiento de la operación subyacente de larga duración 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 se complete el proceso:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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",
};

async function main() {
  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);
}

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const { delay } = require("@azure/core-util");

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

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

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

main();

Obtención de 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.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  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
  );
}

main();

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

El diseño de Azure Key Vault distingue claramente entre claves, secretos y certificados. Las características certificados del servicio Key Vault se diseñaron haciendo uso de sus funcionalidades de claves y secretos. Vamos a evaluar la composición de un certificado de Key Vault:

Cuando se crea un certificado de Key Vault, se crean también una clave direccionable y un secreto con el mismo nombre. La clave de Key Vault permite las operaciones de clave y el secreto de Key Vault permite la recuperación del valor del certificado como un secreto. Un certificado de Key Vault también contiene metadatos del certificado X.509 público. Origen: composición de un certificado.

Sabiendo que la clave privada se almacena en un secreto de Key Vault, con el certificado público incluido, podemos recuperarla mediante el cliente de secretos de Key Vault.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// 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:
fs.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.

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 desea trabajar con certificados en formato PEM, puede indicar al servicio de Key Vault de Azure que cree y administre los certificados en formato PEM proporcionando la contentType propiedad en el momento de crear los certificados.

En el ejemplo siguiente se muestra cómo crear y recuperar las partes públicas y privadas de un certificado con formato PEM mediante los clientes de Key Vault para certificados y secretos:

// 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.
});
const keyVaultCertificate = 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

listPropertiesOfCertificatesenumerará todos los certificados del Key Vault.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

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:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  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",
  });
}

main();

Eliminación de un certificado

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

Si la eliminación temporal está habilitada para la 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.

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

async function main() {
  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);
}

main();

Dado que la eliminación de un certificado no se producirá al instante, se necesita algún tiempo después de llamar al beginDeleteCertificate método antes de que el certificado eliminado esté disponible para que se lea, recupere o purgue.

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 mostrará todos los certificados no eliminados por sus nombres, solo en sus versiones más recientes.
  • listDeletedCertificates mostrará todos los certificados eliminados por sus nombres, solo en sus versiones más recientes.
  • listPropertiesOfCertificateVersions mostrará todas las versiones de un certificado en función de un nombre de certificado.

Que se puede usar de la siguiente manera:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

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

main();

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:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@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";

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

main();

Solución de problemas

La habilitación del registro puede ayudar a descubrir información útil sobre los 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 @azure/logger:

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

setLogLevel("info");

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Pasos siguientes

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

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones