Partilhar via

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

  • Artigo

O Azure Key Vault Managed HSM é um serviço cloud totalmente gerido, altamente disponível, de inquilino único e compatível com normas, que lhe permite salvaguardar chaves criptográficas para as suas aplicações na cloud através de HSMs validados de Nível 3 FIPS 140-2. Se quiser saber mais sobre o Azure Key Vault O HSM Gerido, poderá querer rever: O que é o Azure Key Vault O HSM Gerido?

O pacote @azure/keyvault-admin fornece suporte para tarefas de Key Vault administrativas, tais como cópia de segurança completa/restauro e controlo de acesso baseado em funções (RBAC) ao nível da chave.

Nota: a biblioteca de Administração só funciona com o Azure Key Vault HSM Gerido – as funções direcionadas para um Key Vault falharão.

Nota: este pacote não pode ser utilizado no browser devido às limitações do serviço Key Vault do Azure. Consulte este documento para obter orientações.

Ligações principais:

Introdução

Instalar o pacote

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

npm install @azure/keyvault-admin

Configurar o TypeScript

Os utilizadores do TypeScript precisam de ter definições de tipo de Nó instaladas:

npm install @types/node

Também tem de ativar compilerOptions.allowSyntheticDefaultImports no seu tsconfig.json. Tenha em atenção que, se tiver ativado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está ativado por predefinição. Consulte o manual de opções do compilador do TypeScript para obter mais informações.

Ambientes atualmente suportados

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, terá de criar uma instância da KeyVaultAccessControlClient classe ou da KeyVaultBackupClient classe, bem como um URL do cofre (que poderá ver como "Nome DNS" no portal do Azure) e um objeto de credencial. Os exemplos apresentados neste documento utilizam um objeto de credencial com o nome DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento local e de produção. Além disso, recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção.

Pode encontrar mais informações sobre diferentes formas de autenticação e os respetivos tipos de credenciais correspondentes na documentação do Azure Identity.

Criar KeyVaultAccessControlClient

Depois de autenticar com o método de autenticação que melhor lhe convém, pode criar o KeyVaultAccessControlClient seguinte, substituindo o URL do HSM Gerido 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, pode criar o KeyVaultBackupClient seguinte, substituindo o URL do HSM Gerido 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);

Conceitos-chave

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, escrita e eliminação. 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 um principal de serviço. Podem ser criados, listados, obtidos individualmente e eliminados.

KeyVaultAccessControlClient

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

KeyVaultBackupClient

A KeyVaultBackupClient fornece operações para realizar cópias de segurança de chaves completas, restauros de chaves completas e restauros seletivos de chaves.

Operações de execução prolongada

As operações efetuadas pelos KeyVaultBackupClient recursos do Azure podem demorar tanto tempo quanto necessário, exigindo uma camada de cliente para controlar, serializar e retomar as operações através do ciclo de vida dos programas que aguardam que sejam concluídas. Isto é feito através de uma abstração comum através do pacote @azure/core-lro.

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

  • beginBackup, começa a gerar uma cópia de segurança de um Azure Key Vault HSM Gerido na conta de Blob de Armazenamento especificada.
  • beginRestore, começa a restaurar todos os materiais-chave com o token de SAS que aponta para uma pasta de cópia de segurança de armazenamento de Blobs do Azure armazenada anteriormente.
  • beginSelectiveRestore, começa a restaurar todas as versões principais de uma determinada chave com o token SAS fornecido pelo utilizador que aponta para uma pasta de cópia de segurança de armazenamento de Blobs do Azure armazenada anteriormente.

Os métodos que iniciam operações de execução prolongada devolvem um poller que lhe permite esperar indefinidamente até que a operação esteja concluída. Estão disponíveis mais informações nos exemplos abaixo.

Exemplos

Temos exemplos em JavaScript e TypeScript que mostram o controlo de acesso e as funcionalidades de cópia de segurança/restauro neste pacote. Siga os readmes correspondentes para obter passos detalhados para executar os exemplos.

Resolução de problemas

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

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Passos seguintes

Pode encontrar mais exemplos de código através das seguintes ligações:

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Impressões