Biblioteca de clientes de Certificados do Azure Key Vault para JavaScript – versão 4.9.0

Artigo
10/17/2024

O Azure Key Vault é um serviço de nuvem que fornece armazenamento seguro e gerenciamento automatizado de certificados usados em um aplicativo de nuvem. Vários certificados e várias versões do mesmo certificado podem ser mantidos no Azure Key Vault. Cada certificado no cofre tem uma política associada a ele que controla a emissão e o tempo de vida do certificado, juntamente com ações a serem tomadas como certificados próximos à expiração.

Se você quiser saber mais sobre o Azure Key Vault, talvez queira examinar: O que é o Azure Key Vault?

Use a biblioteca de clientes para certificados do Azure Key Vault em seu aplicativo Node.js para:

Obter, definir e excluir um certificado.
Atualize um certificado, seus atributos, emissor, política, operação e contatos.
Faça backup e restaure um certificado.
Obter, limpar ou recuperar um certificado excluído.
Obtenha todas as versões de um certificado.
Obtenha todos os certificados.
Obtenha todos os certificados excluídos.

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:

código-fonte
do pacote (npm)
documentação de referência da API
documentação do produto
exemplos de

Introdução

Ambientes com suporte no momento

versões lts do Node.js

Pré-requisitos

Uma assinatura do Azure
Umexistente do Azure Key Vault . Se você precisar criar um cofre de chaves, poderá fazê-lo no Portal do Azure seguindo as etapas em este documento. Como alternativa, use a CLI do Azure seguindo estas etapas.

Instalar o pacote

Instalar a biblioteca de clientes de Certificados do Azure Key Vault usando o npm

npm install @azure/keyvault-certificates

Instalar a biblioteca de identidades

Os clientes do Key Vault são autenticados usando a Biblioteca de Identidade do Azure. Instalá-lo também usando o npm

npm install @azure/identity

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.

Autenticação com o Azure Active Directory

O serviço do Key Vault depende do Azure Active Directory para autenticar solicitações para suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. O README para @azure/identity fornece mais detalhes e exemplos para você começar.

Para interagir com o serviço do Azure Key Vault, você precisará criar uma instância da classe CertificateClient, uma url do cofre 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.

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e CertificateClient:

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

Depois que eles forem importados, poderemos nos conectar ao serviço do cofre de chaves:

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

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our certificates client and connect to the service
const client = new CertificateClient(url, credential);

Principais conceitos

O cliente Certificates é a interface principal para interagir com os métodos de API relacionados a certificados na API do Azure Key Vault de um aplicativo JavaScript. Depois de inicializado, ele fornece um conjunto básico de métodos que podem ser usados para criar, ler, atualizar e excluir certificados.
Uma versão do certificado é uma versão de um certificado no Key Vault. Sempre que um usuário atribui um valor a um nome de certificado exclusivo, uma nova versão desse certificado é criada. A recuperação de um certificado por um nome sempre retornará o valor mais recente atribuído, a menos que uma versão específica seja fornecida à consulta.
exclusão reversível permite que os Key Vaults ofereçam suporte à exclusão e à limpeza como duas etapas separadas, portanto, os certificados excluídos não são perdidos imediatamente. Isso só acontecerá se o Key Vault tiver de exclusão reversível habilitada.
Uma de backup de certificado pode ser gerada a partir de qualquer certificado criado. Esses backups vêm como dados binários e só podem ser usados para regenerar um certificado excluído anteriormente.

Especificando a versão da API de serviço do Azure Key Vault

Por padrão, esse pacote usa a versão mais recente do serviço do Azure Key Vault, que é 7.1. A única outra versão com suporte é 7.0. Você pode alterar a versão do serviço que está sendo usada definindo a opção serviceVersion no construtor do cliente, conforme mostrado abaixo:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

Exemplos

As seções a seguir fornecem snippets de código que abrangem algumas das tarefas comuns usando certificados do Azure Key Vault. Os cenários abordados aqui consistem em:

Criando e definindo um certificado.
obtendo um certificado do Key Vault.
Obter as informações completas de um certificado.
Certificados no formato PEM.
Listar todos os certificados.
Atualizar um certificado.
excluir um certificado.
listas de iteração de certificados.

Criando e definindo um certificado

beginCreateCertificate cria um certificado a ser armazenado no Azure Key Vault. Se já existir um certificado com o mesmo nome, uma nova versão do certificado será criada.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.beginCreateCertificate(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Além do nome do certificado e da política, você também pode passar as seguintes propriedades em um terceiro argumento com valores opcionais:

enabled: um valor booliano que determina se o certificado pode ser usado ou não.
tags: qualquer conjunto de valores-chave que possa ser usado para pesquisar e filtrar certificados.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

async function main() {
  await client.beginCreateCertificate(certificateName, certificatePolicy, {
    enabled,
    tags,
  });
}

main();

Chamar beginCreateCertificate com o mesmo nome criará uma nova versão do mesmo certificado, que terá os atributos fornecidos mais recentes.

Como os Certificados levam algum tempo para serem totalmente criados, beginCreateCertificate retorna um objeto poller que acompanha a Operação de Execução Longa subjacente de acordo com nossas diretrizes: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

O sondador recebido permitirá que você obtenha o certificado criado chamando para poller.getResult(). Você também pode aguardar até que a exclusão seja concluída, executando chamadas de serviço individuais até que o certificado seja criado ou aguardando até que o processo seja concluído:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  // You can use the pending certificate immediately:
  const pendingCertificate = poller.getResult();

  // Or you can wait until the certificate finishes being signed:
  const keyVaultCertificate = await poller.pollUntilDone();
  console.log(keyVaultCertificate);
}

main();

Outra maneira de aguardar até que o certificado seja assinado é fazer chamadas individuais, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The certificate ${certificateName} is fully created`);
}

main();

Obtendo um certificado do Key Vault

A maneira mais simples de ler certificados de volta do cofre é obter um certificado por nome. getCertificate recuperará a versão mais recente do certificado, juntamente com a política do certificado. Opcionalmente, você pode obter uma versão diferente do certificado chamando getCertificateVersion se especificar a versão. getCertificateVersion não retorna a política do certificado.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const latestCertificate = await client.getCertificate(certificateName);
  console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
  const specificCertificate = await client.getCertificateVersion(
    certificateName,
    latestCertificate.properties.version
  );
  console.log(
    `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
    specificCertificate
  );
}

main();

Obtendo as informações completas de um certificado

O design do Azure Key Vault faz distinções acentuadas entre Chaves, Segredos e Certificados. Os recursos de Certificados do serviço key vault foram projetados usando seus recursos de Chaves e Segredos. Vamos avaliar a composição de um certificado do Key Vault:

Quando um certificado do Key Vault é criado, uma chave endereçável e um segredo também são criados com o mesmo nome. A chave do Key Vault permite operações de chave e o segredo do Key Vault permite a recuperação do valor do certificado como um segredo. Um certificado do Key Vault também contém metadados de certificado x509 públicos. Fonte: Composição de um certificado.

Sabendo que a chave privada é armazenada em um Segredo do Key Vault, com o certificado público incluído, podemos recuperá-la usando o cliente segredos do Key Vault.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

Observe que, por padrão, o tipo de conteúdo dos certificados é PKCS 12. Ao especificar o tipo de conteúdo do seu certificado, você poderá recuperá-lo no formato PEM. Antes de mostrar como criar certificados PEM, primeiro vamos explorar como recuperar uma chave secreta PEM de um certificado PKCS 12 primeiro.

Usando openssl, você pode recuperar o certificado público no formato PEM usando o seguinte comando:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

Você também pode usar openssl para recuperar a chave privada, da seguinte maneira:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Observe que, em ambos os casos, o openssl solicitará a senha usada para criar o certificado. O código de exemplo que usamos até agora não especificou uma senha, portanto, você pode acrescentar -passin 'pass:' ao final de cada comando.

Certificados no formato PEM

Se você quiser trabalhar com certificados no formato PEM, poderá dizer ao serviço key vault do Azure para criar e gerenciar seus certificados no formato PEM fornecendo a propriedade contentType no momento da criação dos certificados.

O exemplo a seguir mostra como criar e recuperar as partes públicas e privadas de um certificado formatado em PEM usando os clientes do Key Vault para Certificados e Segredos:

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Tenha em mente que seu certificado público estará no mesmo blob de conteúdo que sua chave privada. Você pode usar os cabeçalhos PEM para extraí-los adequadamente.

Listar todos os certificados

listPropertiesOfCertificates listará todos os certificados no Key Vault.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

Atualizando um certificado

Os atributos de certificado podem ser atualizados para uma versão de certificado existente com updateCertificate, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

A política do certificado também pode ser atualizada individualmente com updateCertificatePolicy, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = client.getCertificate(certificateName);
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Excluindo um certificado

O método beginDeleteCertificate define um certificado para exclusão. Esse processo ocorrerá em segundo plano assim que os recursos necessários estiverem disponíveis.

Se de exclusão reversível estiver habilitada para o Key Vault, essa operação rotulará apenas o certificado como um certificado excluído. Um certificado excluído não pode ser atualizado. Eles só podem ser lidos, recuperados ou limpos.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const poller = await client.beginDeleteCertificate(certificateName);

  // You can use the deleted certificate immediately:
  const deletedCertificate = poller.getResult();

  // The certificate is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted certificate this way:
  await client.getDeletedCertificate(certificateName);

  // Deleted certificates can also be recovered or purged.

  // recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
  // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
  // await recoverPoller.pollUntilDone();

  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

Como a exclusão de um certificado não ocorrerá instantaneamente, algum tempo será necessário depois que o método beginDeleteCertificate for chamado antes que o certificado excluído esteja disponível para ser lido, recuperado ou limpo.

Iterando listas de certificados

Usando o CertificateClient, você pode recuperar e iterar por meio de todos os certificados em um Cofre de Certificados, bem como por todos os certificados excluídos e as versões de um certificado específico. Os seguintes métodos de API estão disponíveis:

listPropertiesOfCertificates listará todos os certificados não excluídos por seus nomes, somente em suas versões mais recentes.
listDeletedCertificates listará todos os certificados excluídos por seus nomes, somente em suas versões mais recentes.
listPropertiesOfCertificateVersions listará todas as versões de um certificado com base em um nome de certificado.

Que pode ser usado da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
  for await (let deletedCertificate of client.listDeletedCertificates()) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(
    certificateName
  )) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

Todos esses métodos retornarão todos os resultados disponíveis ao mesmo tempo. Para recuperá-los por páginas, adicione .byPage() logo após invocar o método de API que você deseja usar, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let page of client.listPropertiesOfCertificates().byPage()) {
    for (let certificateProperties of page) {
      console.log("Certificate properties: ", certificateProperties);
    }
  }
  for await (let page of client.listDeletedCertificates().byPage()) {
    for (let deletedCertificate of page) {
      console.log("Deleted certificate: ", deletedCertificate);
    }
  }
  for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
    for (let certificateProperties of page) {
      console.log("Properties of certificate: ", certificateProperties);
    }
  }
}

main();

Solucionando problemas

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

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

Próximas etapas

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

Exemplos de Certificados do Key Vault (JavaScript)
exemplos de certificados do Key Vault (TypeScript)
casos de teste de certificados do Key Vault

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.

impressões

Compartilhar via