Início rápido: Biblioteca de clientes de certificado do Azure Key Vault para JavaScript (versão 4)

Introdução à biblioteca de clientes de certificados do Azure Key Vault para JavaScript. O Azure Key Vault é um serviço de nuvem que funciona como um repositório seguro de certificados. Você pode armazenar chaves, senhas, certificados e outros segredos com segurança. Os cofres de chaves do Azure podem ser criados e gerenciados por meio do portal do Azure. Neste guia de início rápido, você aprenderá a criar, recuperar e excluir certificados de um cofre de chaves do Azure usando a biblioteca de clientes do JavaScript

Recursos da biblioteca de clientes do Key Vault:

Documentação de referência da API | Código-fonte da biblioteca | Pacote (npm)

Para obter mais informações sobre o Key Vault e os certificados, confira:

Pré-requisitos

Este início rápido pressupõe que você esteja executando a CLI do Azure.

Entrar no Azure

  1. Execute o comando login.

    az login
    

    Se a CLI puder abrir o navegador padrão, ela o fará e carregará uma página de entrada do Azure.

    Caso contrário, abra uma página de navegador em https://aka.ms/devicelogin e insira o código de autorização exibido no terminal.

  2. Entre com suas credenciais de conta no navegador.

Criar um aplicativo Node.js

Em seguida, crie um aplicativo Node.js que possa ser implantado na nuvem.

  1. Em um shell de comando, crie uma pasta chamada key-vault-node-app:
mkdir key-vault-node-app
  1. Altere para o diretório key-vault-node-app recém-criado e execute o comando "nit" para inicializar o projeto do Node:
cd key-vault-node-app
npm init -y

Instalar pacotes do Key Vault

Na janela do console, instale a biblioteca de certificados do Azure Key Vault para Node.js.

npm install @azure/keyvault-certificates

Instalar o pacote azure.identity para autenticar em um Key Vault

npm install @azure/identity

Definir variáveis de ambiente

Este aplicativo usa o nome do cofre de chaves como uma variável de ambiente chamada KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS ou Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Permitir acesso ao cofre de chaves

Crie uma política de acesso para o cofre de chaves que conceda permissões de certificado à sua conta de usuário

az keyvault set-policy --name <YourKeyVaultName> --upn user@domain.com --certificate-permissions delete get list create purge

Exemplos de código

Os exemplos de código abaixo mostrarão como criar um cliente, definir um certificado, recuperar um certificado e excluir um certificado.

Configurar o framework de aplicativos

  1. Crie um arquivo de texto e salve-o como "index.js"

  2. Adicione chamadas necessárias para carregar os módulos do Azure e do Node.js

  3. Crie a estrutura do programa, incluindo um tratamento de exceções básico

const readline = require('readline');

function askQuestion(query) {
    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
    });

    return new Promise(resolve => rl.question(query, ans => {
        rl.close();
        resolve(ans);
    }))
}

async function main() {
    
}

main().then(() => console.log('Done')).catch((ex) => console.log(ex.message));

Adicionar diretivas

Adicione as seguintes diretivas à parte superior de seu código:

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

Autenticar e criar um cliente

Neste guia de início rápido, o usuário conectado é usado para se autenticar no cofre de chaves, que é o método preferencial para o desenvolvimento local. Para os aplicativos implantados no Azure, a identidade gerenciada deve ser atribuída ao Serviço de Aplicativo ou à Máquina Virtual. Para obter mais informações, confira Visão geral da identidade gerenciada.

No exemplo abaixo, o nome do cofre de chaves é expandido para o URI do cofre de chaves, no formato "https://<your-key-vault-name>.vault.azure.net". Este exemplo usa a classe 'DefaultAzureCredential()' da Biblioteca de Identidades do Azure, que permite usar o mesmo código em diferentes ambientes com outras opções para fornecer a identidade. Para obter mais informações sobre como se autenticar no cofre de chaves, confira Guia do Desenvolvedor.

Adicione o código a seguir à função 'main()'

const keyVaultName = process.env["KEY_VAULT_NAME"];
const KVUri = "https://" + keyVaultName + ".vault.azure.net";

const credential = new DefaultAzureCredential();
const client = new Certificate(KVUri, credential);

Salvar um certificado

Agora que o aplicativo foi autenticado, você pode colocar um certificado em seu cofre de chaves usando o método beginCreateCertificate. Isso requer um nome para o certificado e a política de certificaçãopolítica de certificação com propriedades de política de certificação

const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert"
};
const createPoller = await client.beginCreateCertificate(certificateName, certificatePolicy);
const certificate = await poller.pollUntilDone();

Observação

Se o nome do certificado existir, o código acima criará uma versão desse certificado.

Recuperar um certificado

Agora, você pode recuperar o valor definido anteriormente com o método getCertificate.

const retrievedCertificate = await client.getCertificate(certificateName);

Excluir um certificado

Por fim, vamos excluir e limpar o certificado do cofre de chaves com os métodos beginDeleteCertificate e purgeDeletedCertificate.

const deletePoller = await client.beginDeleteCertificate(certificateName);
await deletePoller.pollUntilDone();
await client.purgeDeletedCertificate(certificateName);

Código de exemplo

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

const readline = require('readline');

function askQuestion(query) {
    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
    });

    return new Promise(resolve => rl.question(query, ans => {
        rl.close();
        resolve(ans);
    }))
}

async function main() {

  const string certificateName = "myCertificate";
  const keyVaultName = process.env["KEY_VAULT_NAME"];
  const KVUri = "https://" + keyVaultName + ".vault.azure.net";

  const credential = new DefaultAzureCredential();
  const client = new CertificateClient(KVUri, credential);

  console.log("Creating a certificate in " + keyVaultName + " called '" + certificateName +  "` ...");
  const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert"
  };
  const createPoller = await client.beginCreateCertificate(certificateName, certificatePolicy);
  const certificate = await poller.pollUntilDone();

  console.log("Done.");

  console.log("Retrieving your certificate from " + keyVaultName + ".");

  const retrievedCertificate = await client.getCertificate(certificateName);

  console.log("Your certificate version is '" + retrievedCertificate.properties.version + "'.");

  console.log("Deleting your certificate from " + keyVaultName + " ...");
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  await deletePoller.pollUntilDone();
  console.log("Done.");
  
  console.log("Purging your certificate from {keyVaultName} ...");
  await client.purgeDeletedCertificate(certificateName);
  
}

main().then(() => console.log('Done')).catch((ex) => console.log(ex.message));

Testar e verificar

Execute os comandos a seguir para executar o aplicativo.

npm install
npm index.js

Uma variação do seguinte resultado é exibida:

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done 

Próximas etapas

Neste guia de início rápido, você criou um cofre de chaves e armazenou e recuperou um certificado. Para saber mais sobre o Key Vault e como integrá-lo a seus aplicativos, confira os artigos abaixo.