Biblioteca de clientes do Azure Key Vault Certificates para JavaScript – versão 4.8.0

  • Artigo

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 Key Vault 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 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 de Key Vault do Azure 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.
  • Obter todos os certificados excluídos.

Observação: este 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 principais:

Introdução

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote

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

npm install @azure/keyvault-certificates

Instalar a biblioteca de identidade

Key Vault clientes se autenticam usando a Biblioteca de Identidade do Azure. Instale-o também usando o npm

npm install @azure/identity

Configurar TypeScript

Os usuários do TypeScript precisam ter definições de tipo de nó 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 será 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 Key Vault depende do Azure Active Directory para autenticar solicitações em suas APIs. O @azure/identity pacote fornece uma variedade de tipos de credenciais que seu aplicativo pode usar para fazer isso. O LEIAME para @azure/identity fornece mais detalhes e exemplos para começar.

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

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 primária 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. Recuperar um certificado por um nome sempre retornará o valor mais recente atribuído, a menos que uma versão específica seja fornecida à consulta.
  • A 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 a exclusão reversível habilitada.
  • Um 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 de serviço do Azure Key Vault

Por padrão, esse pacote usa a versão mais recente do serviço Key Vault do Azure, 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 de Key Vault do Azure. Os cenários abordados aqui consistem em:

Criando e definindo um certificado

beginCreateCertificatecria um certificado a ser armazenado no Key Vault do Azure. Se um certificado com o mesmo nome já existir, 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 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 com beginCreateCertificate 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 de 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 Key Vault do Azure faz distinções acentuadas entre Chaves, Segredos e Certificados. Os recursos de Certificados do serviço Key Vault foram projetados usando os recursos de Chaves e Segredos. Vamos avaliar a composição de um certificado de Key Vault:

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

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

// 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 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, 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á informar o serviço Key Vault do Azure para criar e gerenciar seus certificados no formato PEM, fornecendo a contentType propriedade 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:

// 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

listPropertiesOfCertificateslistará 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 beginDeleteCertificate método define um certificado para exclusão. Esse processo ocorrerá em segundo plano assim que os recursos necessários estiverem disponíveis.

Se a 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 beginDeleteCertificate método for chamado antes que o certificado excluído esteja disponível para leitura, recuperação ou limpeza.

Iterando listas de certificados

Usando o CertificateClient, você pode recuperar e iterar 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 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

A habilitação do 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 log pode ser habilitado no runtime chamando setLogLevel em @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:

Contribuição

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

Impressões