Biblioteca de cliente do Azure Key Vault Certificates 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 Cofre da Chave do Azure. 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 as ações a serem tomadas como certificados perto do vencimento.

Se quiser saber mais sobre o Azure Key Vault, consulte: O que é o Azure Key Vault?

Use a biblioteca de cliente para Certificados do Cofre de Chaves do Azure em seu aplicativo Node.js para:

Obtenha, defina e exclua um certificado.
Atualize um certificado, seus atributos, emissor, política, operação e contatos.
Faça backup e restaure um certificado.
Obtenha, limpe ou recupere um certificado excluído.
Obtenha todas as versões de um certificado.
Obtenha todos os certificados.
Obtenha todos os certificados excluídos.

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:

Código fonte
Pacote (npm)
de documentação de referência da API
Documentação do produto
Amostras

Primeiros passos

Ambientes atualmente suportados

versões LTS do Node.js

Pré-requisitos

Uma assinatura do Azure
Um existente do Azure Key Vault. Se precisar de criar um cofre de chaves, pode fazê-lo no Portal do Azure seguindo os passos indicados em este documento. Como alternativa, use a CLI do Azure seguindo estas etapas.

Instalar o pacote

Instalar a biblioteca de cliente de Certificados do Cofre de Chaves do Azure usando npm

npm install @azure/keyvault-certificates

Instalar a biblioteca de identidades

Os clientes do Cofre da Chave são autenticados usando a Biblioteca de Identidades do Azure. Instale-o também usando npm

npm install @azure/identity

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.

Autenticação com o Azure Ative Directory

O serviço Cofre da Chave depende do Azure Ative Directory para autenticar solicitações para suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credenciais 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 , um de 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 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.

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, podemos nos conectar em seguida ao serviço de 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);

Conceitos-chave

O de cliente de Certificados é a interface principal para interagir com os métodos de API relacionados a certificados na API do Cofre de Chaves do Azure a partir de um aplicativo JavaScript. Uma vez inicializado, ele fornece um conjunto básico de métodos que podem ser usados para criar, ler, atualizar e excluir certificados.
Uma versão Certificado é uma versão de um certificado no Cofre da Chave. Cada vez 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.
de exclusão suave permite que os Cofres de Chaves suportem a exclusão e a limpeza como duas etapas separadas, para que os certificados excluídos não sejam imediatamente perdidos. Isso só acontece se o Cofre da Chave tiver de exclusão suave habilitada.
Um de backup de certificado pode ser gerado 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, esse pacote usa a versão mais recente do serviço Azure Key Vault, que é 7.1. A única outra versão suportada é 7.0. Você pode alterar a versão de 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 trechos de código que abrangem algumas das tarefas comuns usando os Certificados do Cofre de Chaves do Azure. Os cenários aqui abordados consistem em:

Criação e configuração de um certificado.
Obter um certificado do Cofre da Chave.
Obter as informações completas de um certificado.
Certificados em formato PEM.
Listar todos os certificados.
Atualizando um certificado.
Excluir um certificado.
Iteração de listas de certificados.

Criar e definir um certificado

beginCreateCertificate cria um certificado para ser armazenado no Cofre da Chave do Azure. Se já existir um certificado com o mesmo nome, é criada uma nova versão 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() {
  // 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 booleano que determina se o certificado pode ser usado ou não.
tags: Qualquer conjunto de valores-chave que podem ser usados 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 para 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 controla a Operação de Longa Execução subjacente de acordo com nossas diretrizes: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

O poller recebido permitirá que você obtenha o certificado criado ligando para poller.getResult(). Você também pode esperar até que a exclusão termine, 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 esperar 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();

Obter um certificado do Cofre da Chave

A maneira mais simples de ler certificados de volta do cofre é obter um certificado pelo 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();

Obter todas as informações 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 usando seus recursos de Chaves e Segredos. Vamos avaliar a composição de um certificado do Key Vault:

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

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

// 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, vamos primeiro 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, então você pode anexá-passin 'pass:' ao final de cada comando.

Certificados em formato PEM

Se quiser trabalhar com certificados no formato PEM, você pode dizer ao serviço Cofre da Chave 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ública e privada de um certificado formatado PEM usando os clientes do Cofre da Chave 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);

Lembre-se de 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 de acordo.

Listar todos os certificados

listPropertiesOfCertificates listará todos os certificados no Cofre da Chave.

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

Atualizar 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 forma:

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

Eliminar um certificado

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

Se de exclusão suave estiver habilitada para o Cofre da Chave, 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 expurgados.

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 acontecerá instantaneamente, é necessário algum tempo depois que o método beginDeleteCertificate é chamado antes que o certificado excluído esteja disponível para ser lido, recuperado ou limpo.

Iteração de listas de certificados

Usando o CertificateClient, você pode recuperar e iterar todos os certificados em um Cofre de Certificados, bem como 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 seus certificados não excluídos por seus nomes, apenas em suas versões mais recentes.
listDeletedCertificates listará todos os seus certificados excluídos por seus nomes, apenas em suas versões mais recentes.
listPropertiesOfCertificateVersions listará todas as versões de um certificado com base no nome de um certificado.

Que pode ser usado da seguinte forma:

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 de uma só vez. 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();

Solução de 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 tempo de execução 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óximos passos

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

Contribuição

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

Impressões

Partilhar via