Compartilhar via

Biblioteca de clientes da Administração Key Vault do Azure para JavaScript – versão 4.5.0

  • Artigo

O Azure Key Vault O HSM Gerenciado é um serviço de nuvem totalmente gerenciado, altamente disponível, de locatário único e compatível com padrões, que permite proteger chaves criptográficas para seus aplicativos de nuvem usando HSMs validados fips 140-2 nível 3. Se você quiser saber mais sobre o HSM gerenciado do Azure Key Vault, talvez queira examinar: O que é o HSM gerenciado do Azure Key Vault?

O pacote @azure/keyvault-admin fornece suporte para tarefas de Key Vault administrativas, como backup/restauração completo e RBAC (controle de acesso baseado em função) no nível da chave.

Observação: a biblioteca administração só funciona com o HSM gerenciado do Azure Key Vault – as funções direcionadas a um Key Vault falharão.

Observação: este pacote não pode ser usado no navegador devido a limitações de serviço do Azure Key Vault, consulte este documento para obter diretrizes.

Links principais:

Introdução

Instalar o pacote

Instale a biblioteca de clientes de administração do Azure Key Vault para JavaScript e TypeScript com NPM:

npm install @azure/keyvault-admin

Configurar TypeScript

Os usuários do TypeScript precisam ter definições de tipo de nó instaladas:

npm install @types/node

Você também precisa habilitar compilerOptions.allowSyntheticDefaultImports em seu tsconfig.json. Observe que, se você tiver habilitado compilerOptions.esModuleInterop, allowSyntheticDefaultImports será habilitado por padrão. Consulte o manual de opções do compilador do TypeScript para obter mais informações.

Ambientes com suporte no momento

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço de Key Vault do Azure, você precisará criar uma instância da KeyVaultAccessControlClient classe ou da KeyVaultBackupClient classe, bem como uma URL do cofre (que você pode ver como "Nome DNS" no Portal do Azure) e um objeto de credencial. Os exemplos mostrados neste documento usam um objeto de credencial chamado DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, recomendamos usar uma identidade gerenciada para autenticação em ambientes de produção.

Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credencial correspondentes na documentação da Identidade do Azure.

Criar KeyVaultAccessControlClient

Depois de autenticar com o método de autenticação que melhor lhe convém, você pode criar um KeyVaultAccessControlClient da seguinte maneira, substituindo na URL do HSM Gerenciado no construtor:

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

const credentials = new DefaultAzureCredential();

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

Criar KeyVaultBackupClient

Depois de autenticar com o método de autenticação que melhor lhe convém, você pode criar um KeyVaultBackupClient da seguinte maneira, substituindo na URL do HSM Gerenciado no construtor:

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

const credentials = new DefaultAzureCredential();

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

Principais conceitos

KeyVaultRoleDefinition

Uma Definição de Função é uma coleção de permissões. Uma definição de função define as operações que podem ser executadas, como leitura, gravação e exclusão. Ele também pode definir as operações excluídas das operações permitidas.

As definições de função podem ser listadas e especificadas como parte de um KeyVaultRoleAssignment.

KeyVaultRoleAssignment

Uma Atribuição de Função é a associação de uma Definição de Função a uma entidade de serviço. Eles podem ser criados, listados, buscados individualmente e excluídos.

KeyVaultAccessControlClient

Um KeyVaultAccessControlClient fornece operações que permitem o gerenciamento de Definições de Função (instâncias de ) e Atribuições de KeyVaultRoleDefinitionFunção (instâncias de KeyVaultRoleAssignment).

KeyVaultBackupClient

Um KeyVaultBackupClient fornece operações para executar backups de chave completa, restaurações de chave completa e restaurações seletivas de chave.

Operações de execução prolongada

As operações feitas pelo KeyVaultBackupClient podem levar tanto tempo quanto o necessário pelos recursos do Azure, exigindo que uma camada de cliente acompanhe, serialize e retome as operações por meio do ciclo de vida dos programas que esperam sua conclusão. Isso é feito por meio de uma abstração comum por meio do pacote @azure/core-lro.

O KeyVaultBackupClient oferece três métodos que executam operações de execução prolongada:

  • beginBackup, inicia a geração de um backup de um HSM gerenciado do Azure Key Vault na conta de Blob de Armazenamento especificada.
  • beginRestore, inicia a restauração de todos os materiais de chave usando o token SAS apontando para uma pasta de backup do Armazenamento de Blobs do Azure armazenada anteriormente.
  • beginSelectiveRestore, inicia a restauração de todas as versões principais de uma determinada chave usando o token SAS fornecido pelo usuário apontando para uma pasta de backup do Armazenamento de Blobs do Azure armazenada anteriormente.

Os métodos que iniciam operações de execução prolongada retornam um sondador que permite aguardar indefinidamente até que a operação seja concluída. Mais informações estão disponíveis nos exemplos abaixo.

Exemplos

Temos exemplos em JavaScript e TypeScript que mostram os recursos de controle de acesso e backup/restauração neste pacote. Siga as leituras correspondentes para obter etapas detalhadas para executar os exemplos.

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Próximas etapas

Você pode encontrar mais exemplos de código por meio dos seguintes links:

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões