Azure Key Vault Secret client library for JavaScript - versión 4.11.1

Azure Key Vault es un servicio que te permite cifrar claves de autenticación, claves de cuentas de almacenamiento, claves de cifrado de datos, archivos .pfx y contraseñas utilizando claves seguras. Si quieres saber más sobre Azure Key Vault, quizá quieras revisar: ¿Qué es Azure Key Vault?

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

Utiliza la biblioteca cliente para Azure Key Vault Secretos en tu Node.js aplicación para:

Obtiene, establece y elimina secretos.
Actualice un secreto y sus atributos.
Copia de seguridad y restauración de un secreto.
Obtenga, purgue o recupere un secreto eliminado.
Obtenga todas las versiones de un secreto.
Obtenga todos los secretos.
Obtenga todos los secretos 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:

Código fuente
Paquete (npm)
documentación de referencia de api de
Documentación del producto
Samples

Cómo empezar

Entornos admitidos actualmente

Versiones de LTS de Node.js

Prerrequisitos

Una suscripción Azure
Un recurso Key Vault
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, puedes usar el CLI de Azure siguiendo los pasos de este documento.

Instalación del paquete

Instala la biblioteca cliente Azure Key Vault Secret usando npm:

npm install @azure/keyvault-secrets

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.

Conceptos clave

El cliente Secret es la interfaz principal para interactuar con los métodos API relacionados con los secretos en la API Azure Key Vault de 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 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.
eliminación temporal permite a los almacenes de claves admitir la eliminación y purga como dos pasos independientes, por lo que los secretos eliminados no se pierden inmediatamente. Esto solo ocurre si el Key Vault tiene activado soft-delete.
Se puede generar una de copia de seguridad de secretos a partir de cualquier secreto creado. Estas copias de seguridad se incluyen como datos binarios y solo se pueden usar para regenerar un secreto eliminado previamente.

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 SecretClient, 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 SecretClient. Una vez importados, podemos conectarnos al servicio Key Vault:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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);

En el caso de los entornos del explorador, use el InteractiveBrowserCredential del paquete de @azure/identity para autenticarse.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

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 { SecretClient } from "@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`;

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

Ejemplos

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

Crear y establecer un secreto.
Obtener un secreto.
Creación y actualización de secretos con atributos.
Eliminar un secreto.
iteración de listas de secretos.

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.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

Obtención de un secreto

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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.

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Borrar un secreto

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Dado que los secretos tardan algún tiempo en eliminarse por completo, 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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

Iteración de listas de secretos

Usando el SecretClient, puedes recuperar e iterar por todos los secretos de un Key Vault, así como por todos los secretos eliminados y las versiones de un secreto específico. Los siguientes métodos de API están disponibles:

listPropertiesOfSecrets enumerará todos los secretos no eliminados por sus nombres, solo en sus versiones más recientes.
listDeletedSecrets enumerará 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 manera siguiente:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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 { SecretClient } from "@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";

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

Solución de problemas

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

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

Pasos siguientes

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

Contribución

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.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-09