Compartir a través de

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

  • Artículo

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

El paquete @azure/keyvault-admin proporciona compatibilidad con tareas administrativas Key Vault, como la copia de seguridad o restauración completa y el 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 Key Vault.

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

Instalar el 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 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.

Entornos admitidos actualmente

Requisitos previos

Autenticar el cliente

Para interactuar con el servicio Azure Key Vault, deberá crear una instancia de la KeyVaultAccessControlClient clase o la KeyVaultBackupClient clase , así como una dirección URL del almacén (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, puede crear como KeyVaultAccessControlClient se indica a continuación, sustituyendo en la dirección URL de HSM administrada en el constructor:

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

const credentials = new DefaultAzureCredential();

const client = new KeyVaultAccessControlClient(`<your Managed HSM URL>`, credentials);

Creación de KeyVaultBackupClient

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

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

const credentials = new DefaultAzureCredential();

const client = new KeyVaultBackupClient(`<your Managed HSM URL>`, 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 .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

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

KeyVaultBackupClient

Proporciona KeyVaultBackupClient operaciones para realizar copias de seguridad de clave completa, restauraciones de claves completas y restauraciones selectivas de claves.

Operaciones de larga duración

Las operaciones realizadas por 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.

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 Storage Blob 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 anteriormente.
  • beginSelectiveRestore, comienza a restaurar todas las versiones de 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 anteriormente.

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éames correspondientes para ver los pasos detallados para ejecutar los ejemplos.

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:

const { setLogLevel } = require("@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