Azure Key Vault Certificates biblioteca cliente para JavaScript - versão 4.10.3

Azure Key Vault é um serviço em nuvem que oferece armazenamento seguro e gerenciamento automatizado de certificados usados em toda uma aplicação em nuvem. Múltiplos certificados, e múltiplas 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 quiser saber mais sobre Azure Key Vault, talvez queira revisar: O que é Azure Key Vault?

Use a biblioteca cliente para Azure Key Vault Certificados em sua Node.js candidatura 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.

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

Links de chave:

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

Introdução

Ambientes com suporte no momento

versões lts do Node.js

Pré-requisitos

Uma assinatura Azure
Um Azure Key Vault existente. Se você precisar criar um cofre de chaves, pode fazer isso no portal do Azure seguindo os passos em este documento. Alternativamente, use o CLI do Azure seguindo esses passos.

Instalar o pacote

Instale a biblioteca cliente Azure Key Vault Certificates usando npm

npm install @azure/keyvault-certificates

Instalar a biblioteca de identidades

Os clientes do Key Vault autenticam 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 Azure Active Directory

O serviço Key Vault depende do Azure Active Directory para autenticar requisições em 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 Azure Key Vault, você precisará criar uma instância da classe CertificateClient, uma URL vault 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 formas de autenticação e seus respectivos tipos de credenciais na Azure Documentação de Identidade.

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e CertificateClient. Depois que eles forem importados, poderemos nos conectar ao serviço do cofre de chaves:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 da API relacionados a certificados na API Azure Key Vault a partir de uma aplicação 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 Certificate é 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ó acontece se o Key Vault tiver soft-delete ativado.
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 do serviço Azure Key Vault

Por padrão, este pacote usa a versão mais recente do serviço 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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.5",
});

Exemplos

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

Criando e definindo um certificado.
Obtendo um certificado de 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 para ser armazenado no Azure Key Vault. Se já existir um certificado com o mesmo nome, uma nova versão do certificado será criada.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

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

Obtendo um certificado 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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 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,
);

Obtendo as informações completas de um certificado

O design do Azure Key Vault faz distinções nítidas entre Chaves, Segredos e Certificados. Os recursos de Certificados do serviço Key Vault foram projetados aproveitando suas capacidades de Chaves e Segredos. Vamos avaliar a composição de um Certificado Key Vault:

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

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

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// 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:
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, pode pedir ao serviço Key Vault da 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 Key Vault para Certificados e Segredos:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// 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.
});
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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

Atualizando um certificado

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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 soft-delete estiver ativado para o Key Vault, essa operação só rotulará o certificado como deleted. Um certificado excluído não pode ser atualizado. Eles só podem ser lidos, recuperados ou limpos.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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

Veja nosso guia solução de problemas para 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:

Contribuindo

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

Comentários

Esta página foi útil?

Last updated on 2026-04-09