Partilhar via

Biblioteca de cliente do Azure Key Vault Administration para JavaScript - versão 4.7.0

O Azure Key Vault Managed HSM é um serviço de nuvem totalmente gerenciado, altamente disponível, de locatário único e compatível com os padrões que permite proteger chaves criptográficas para seus aplicativos em nuvem usando HSMs validados pelo FIPS 140-2 Nível 3. Se quiser saber mais sobre o Azure Key Vault Managed HSM, convém analisar: O que é o Azure Key Vault Managed HSM?

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

Observação: a biblioteca de Administração só funciona com HSM gerenciado do Azure Key Vault - as funções direcionadas a um Cofre de Chaves falharão.

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

Ligações principais:

Como Começar

Instale o pacote

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

npm install @azure/keyvault-admin

Configurar o TypeScript

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

npm install @types/node

Você também precisa ativar compilerOptions.allowSyntheticDefaultImports em seu tsconfig.json. Observe que, se você tiver habilitado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está habilitado por padrão. Consulte 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 Azure Key Vault, você precisará criar uma instância da classe KeyVaultAccessControlClient ou da classe KeyVaultBackupClient, bem como um 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 de desenvolvimento local e produção. Além disso, recomendamos o uso de um de identidade gerenciado para autenticação em ambientes de produção.

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

Criar KeyVaultAccessControlClient

Depois de autenticar com o método de autenticação que melhor se adapta a você, você pode criar um KeyVaultAccessControlClient da seguinte maneira, substituindo sua URL de 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 se adapta a você, você pode criar um KeyVaultBackupClient da seguinte maneira, substituindo sua URL de 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-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, gravação e exclusão. Ele também pode definir as operações que são 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 completos, restaurações de chave completas e restaurações seletivas de chaves.

Operações de longa duração

As operações feitas pelo KeyVaultBackupClient podem levar o tempo necessário para os recursos do Azure, exigindo que uma camada de cliente acompanhe, serialize e retome as operações durante o ciclo de vida dos programas que aguardam sua conclusão. 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 longa duração:

  • 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 materiais de chave usando o token SAS apontando para uma pasta de backup de armazenamento de Blob do Azure armazenada anteriormente.
  • beginSelectiveRestore, começa a restaurar todas as versões de chave de uma determinada chave usando o token SAS fornecido pelo usuário apontando para uma pasta de backup de armazenamento de Blob do Azure armazenada anteriormente.

Os métodos que iniciam operações de longa duração retornam um poller que permite esperar 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 o controle de acesso e os recursos de backup/restauração neste pacote. Siga os readmes correspondentes para obter etapas detalhadas para executar as amostras.

Soluçã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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Você pode encontrar mais exemplos de código através dos seguintes links:

Contribuir

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

  • Last updated on