Compartilhar via

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

O HSM Gerenciado do Azure Key Vault é 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, convém examinar: O que é o HSM Gerenciado do Azure Key Vault?

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

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

Observação: esse 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 de chave:

Como começar

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 node 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 estará 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 do Azure Key Vault, você precisará criar uma instância da classe KeyVaultAccessControlClient ou da classe KeyVaultBackupClient, bem como uma url de 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 do Azure Identity.

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:

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

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:

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

Conceitos principais

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 KeyVaultRoleDefinition) e Atribuições de Funçã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 longa duração

As operações feitas pelo KeyVaultBackupClient podem levar tanto tempo quanto 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 que elas sejam concluídas. 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, começa a gerar um backup de um HSM Gerenciado do Azure Key Vault na conta de Blob de Armazenamento especificada.
  • beginRestore, começa a restaurar todos os principais materiais usando o token SAS apontando para uma pasta de backup de armazenamento de Blobs do Azure armazenada anteriormente.
  • beginSelectiveRestore, começa a restaurar todas as principais versões de uma determinada chave usando o token SAS fornecido pelo usuário apontando para uma pasta de backup de 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 os readmes correspondentes para obter etapas detalhadas para executar os exemplos.

Resolução de problemas

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

Habilitar o registro em 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 registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Próximas etapas

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

Contribuindo

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

  • Last updated on