Compartir a través de

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

  • Artículo

Azure Key Vault es un servicio que permite cifrar claves de autenticación, claves de cuenta de almacenamiento, claves de cifrado de datos, archivos .pfx y contraseñas mediante claves protegidas. Si desea obtener más información sobre Azure Key Vault, puede que desee revisar: ¿Qué es Azure Key Vault?

La administración de secretos de Azure Key Vault permite almacenar y controlar de forma segura el acceso a tokens, contraseñas, certificados, claves de API y otros secretos.

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

  • Obtiene, establece y elimina secretos.
  • Actualice un secreto y sus atributos.
  • Copia de seguridad y restauración de un secreto.
  • Obtener, purgar o recuperar un secreto eliminado.
  • Obtenga todas las versiones de un secreto.
  • Obtenga todos los secretos.
  • Obtenga todos los secretos eliminados.

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

Vínculos principales:

Introducción

Entornos admitidos actualmente

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente secreto de Azure Key Vault mediante npm:

npm install @azure/keyvault-secrets

Instalación de la biblioteca de identidades

Key Vault los clientes se autentican mediante la biblioteca de identidades de Azure. Instálelo también mediante npm

npm install @azure/identity

Configuración de TypeScript

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

npm install @types/node

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

Conceptos clave

  • El cliente secreto es la interfaz principal para interactuar con los métodos de API relacionados con los secretos 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 secretos.
  • Una versión secreta es una versión de un secreto en el Key Vault. Cada vez que un usuario asigna un valor a un nombre de secreto único, se crea una nueva versión de ese secreto. La recuperación de un secreto 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 purgar como dos pasos independientes, por lo que los secretos 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 secreta a partir de cualquier secreto creado. Estas copias de seguridad vienen como datos binarios y solo se pueden usar para regenerar un secreto eliminado previamente.

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 SecretClient 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 SecretClient:

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

Una vez importados, podemos conectarse al servicio Key Vault:

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

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 secrets client and connect to the service
const client = new SecretClient(url, credential);

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 de 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 { SecretClient } = require("@azure/keyvault-secrets");

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 SecretClient(url, credential, {
  serviceVersion: "7.0",
});

Ejemplos

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

Creación y configuración de un secreto

setSecret asigna un valor proporcionado al nombre de secreto especificado. Si ya existe un secreto con el mismo nombre, se crea una nueva versión del secreto.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Obtención de un secreto

La manera más sencilla de leer secretos desde el almacén es obtener un secreto por nombre. Esto recuperará la versión más reciente del secreto. Opcionalmente, puede obtener otra versión de la clave si la especifica como parte de los parámetros opcionales.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

Creación y actualización de secretos con atributos

Un secreto puede tener más información que su nombre y su valor. También pueden incluir los siguientes atributos:

  • tags: cualquier conjunto de valores de clave que se pueden usar para buscar y filtrar secretos.
  • contentType: cualquier cadena que se pueda usar para ayudar al receptor del secreto a comprender cómo usar el valor del secreto.
  • enabled: valor booleano que determina si el valor del secreto se puede leer o no.
  • notBefore: fecha determinada después de la cual se puede recuperar el valor del secreto.
  • expiresOn: fecha determinada después de la cual no se puede recuperar el valor del secreto.

Se puede enviar un objeto con estos atributos como tercer parámetro de setSecret, justo después del nombre y el valor del secreto, como se indica a continuación:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

Esto creará una nueva versión del mismo secreto, que tendrá los atributos proporcionados más recientes.

Los atributos también se pueden actualizar a una versión secreta existente con updateSecretProperties, como se indica a continuación:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

Borrar un secreto

El beginDeleteSecret método inicia la eliminación de un secreto. Este proceso se realizará en segundo plano en cuanto estén disponibles los recursos necesarios.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Si la eliminación temporal está habilitada para la Key Vault, esta operación solo etiquetará el secreto como secreto eliminado. No se puede actualizar un secreto eliminado. Solo se pueden leer, recuperar o purgar.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

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

  // The secret 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 secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

Dado que los secretos tardan algún tiempo en eliminarse completamente, beginDeleteSecret devuelve un objeto Poller 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 secreto eliminado llamando a poller.getResult(). También puede esperar hasta que finalice la eliminación, ya sea ejecutando llamadas de servicio individuales hasta que se elimine el secreto o esperando hasta que se realice el proceso:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

Otra manera de esperar hasta que el secreto se elimine por completo es realizar llamadas individuales, como se indica a continuación:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
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 SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

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

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

Iteración de listas de secretos

Con SecretClient, puede recuperar e iterar todos los secretos de un Key Vault, así como a través de todos los secretos eliminados y las versiones de un secreto específico. Los siguientes métodos de API están disponibles:

  • listPropertiesOfSecrets mostrará todos los secretos no eliminados por sus nombres, solo en sus versiones más recientes.
  • listDeletedSecrets mostrará todos los secretos eliminados por sus nombres, solo en sus versiones más recientes.
  • listPropertiesOfSecretVersions enumerará todas las versiones de un secreto en función de un nombre de secreto.

Que se puede usar de la siguiente manera:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

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 { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

Solución de problemas

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

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

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