Compartir a través de

Biblioteca cliente de Administración de Azure Key Vault para JavaScript: versión 4.7.0

HSM administrado de Azure Key Vault es un servicio en la nube totalmente administrado, de alta disponibilidad, de un solo inquilino y compatible con los estándares que permite proteger las claves criptográficas para las aplicaciones en la nube mediante HSM validados por FIPS 140-2 de nivel 3. Si desea obtener más información sobre HSM administrado de Azure Key Vault, puede que desee revisar: ¿Qué es HSM administrado de Azure Key Vault?

El paquete @azure/keyvault-admin proporciona compatibilidad con tareas administrativas de Key Vault, como copia de seguridad completa o restauración y control de acceso basado en rol (RBAC) de nivel de clave.

Nota: La biblioteca de administración solo funciona con HSM administrado de Azure Key Vault: se producirá un error en las funciones destinadas a un almacén de claves.

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

Cómo empezar

Instalación del paquete

Instale la biblioteca cliente de administración de Azure Key Vault para JavaScript y TypeScript con NPM:

npm install @azure/keyvault-admin

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.

Entornos admitidos actualmente

Prerrequisitos

Autenticación del cliente

Para interactuar con el servicio Azure Key Vault, deberá crear una instancia de la clase KeyVaultAccessControlClient o la clase KeyVaultBackupClient, así como una dirección URL del almacén de (que puede ver como "Nombre DNS" en Azure Portal) 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.

Creación de KeyVaultAccessControlClient

Una vez que se haya autenticado con el método de autenticación que mejor se adapte a, puede crear un KeyVaultAccessControlClient como se indica a continuación, sustituyendo en la dirección URL de HSM administrada en el constructor:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyVaultAccessControlClient } from "@azure/keyvault-admin";

const vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
const credentials = new DefaultAzureCredential();
const client = new KeyVaultAccessControlClient(vaultUrl, credentials);

Creación de KeyVaultBackupClient

Una vez que se haya autenticado con el método de autenticación que mejor se adapte a, puede crear un KeyVaultBackupClient como se indica a continuación, sustituyendo en la dirección URL de HSM administrada en el constructor:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyVaultBackupClient } from "@azure/keyvault-admin";

const vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
const credentials = new DefaultAzureCredential();
const client = new KeyVaultBackupClient(vaultUrl, credentials);

Conceptos clave

KeyVaultRoleDefinition

Una definición de roles es una colección de permisos. Una definición de rol define las operaciones que se pueden realizar, como lectura, escritura y eliminación. También puede definir las operaciones que se excluyen de las operaciones permitidas.

Las definiciones de roles se pueden enumerar y especificar como parte de un KeyVaultRoleAssignment.

KeyVaultRoleAssignment

Una asignación de roles es la asociación de una definición de roles a una entidad de servicio. Se pueden crear, enumerar, capturar individualmente y eliminar.

KeyVaultAccessControlClient

Un KeyVaultAccessControlClient proporciona operaciones que permiten la administración de definiciones de roles (instancias de KeyVaultRoleDefinition) y asignaciones de roles (instancias de KeyVaultRoleAssignment).

KeyVaultBackupClient

Un KeyVaultBackupClient proporciona operaciones para realizar copias de seguridad de claves completas, restauraciones de claves completas y restauraciones selectivas de claves.

Operaciones de larga duración

Las operaciones realizadas por el KeyVaultBackupClient pueden tardar tanto tiempo como lo necesiten los recursos de Azure, lo que requiere que un nivel de cliente realice un seguimiento, serialice y reanude las operaciones a través del ciclo de vida de los programas que esperan a que finalicen. Esto se hace a través de una abstracción común a través del paquete @azure/core-lro.

El KeyVaultBackupClient ofrece tres métodos que ejecutan operaciones de larga duración:

  • beginBackup, comienza a generar una copia de seguridad de un HSM administrado de Azure Key Vault en la cuenta de blob de almacenamiento especificada.
  • beginRestore, comienza a restaurar todos los materiales clave mediante el token de SAS que apunta a una carpeta de copia de seguridad de Azure Blob Storage almacenada previamente.
  • beginSelectiveRestore, comienza a restaurar todas las versiones clave de una clave determinada mediante el token de SAS proporcionado por el usuario que apunta a una carpeta de copia de seguridad de Azure Blob Storage almacenada previamente.

Los métodos que comienzan las operaciones de larga duración devuelven un sondeo que permite esperar indefinidamente hasta que se complete la operación. Puede encontrar más información en los ejemplos siguientes.

Ejemplos

Tenemos ejemplos en JavaScript y TypeScript que muestran las características de control de acceso y copia de seguridad y restauración en este paquete. Siga los léame correspondientes para ver los pasos detallados para ejecutar los ejemplos.

Solución de problemas

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

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 desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.