Partilhar via

Biblioteca de cliente de Certificados do Azure Key Vault para JavaScript – versão 4.8.0

  • Artigo

O Azure Key Vault é um serviço cloud que fornece armazenamento seguro e gestão automatizada de certificados utilizados numa aplicação na cloud. 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 que controla a emissão e a duração do certificado, juntamente com as ações a serem tomadas como certificados perto da expiração.

Se quiser saber mais sobre o Azure Key Vault, poderá querer rever: O que é o Azure Key Vault?

Utilize a biblioteca de cliente para Certificados de Key Vault do Azure na sua aplicação de Node.js para:

  • Obter, definir e eliminar um certificado.
  • Atualize um certificado, os respetivos atributos, emissor, política, operação e contactos.
  • Faça uma cópia de segurança e restaure um certificado.
  • Obter, remover ou recuperar um certificado eliminado.
  • Obtenha todas as versões de um certificado.
  • Obter todos os certificados.
  • Obter todos os certificados eliminados.

Nota: este pacote não pode ser utilizado no browser devido às limitações do serviço Key Vault do Azure. Veja este documento para obter orientações.

Ligações principais:

Introdução

Ambientes atualmente suportados

Pré-requisitos

Instalar o pacote

Instalar a biblioteca de cliente certificados do Azure Key Vault com o npm

npm install @azure/keyvault-certificates

Instalar a biblioteca de identidades

Key Vault os clientes autenticam-se com a Biblioteca de Identidades do Azure. Instale-o também com o npm

npm install @azure/identity

Configurar TypeScript

Os utilizadores do TypeScript precisam de ter definições de tipo de Nó instaladas:

npm install @types/node

Também tem de ativar compilerOptions.allowSyntheticDefaultImports no seu tsconfig.json. Tenha em atenção que, se tiver ativado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está ativado por predefinição. Veja o manual de opções do compilador do TypeScript para obter mais informações.

Autenticar com o Azure Active Directory

O serviço Key Vault depende do Azure Active Directory para autenticar pedidos para as respetivas APIs. O @azure/identity pacote fornece uma variedade de tipos de credenciais que a sua aplicação pode utilizar para o fazer. O README para @azure/identity fornece mais detalhes e exemplos para começar.

Para interagir com o serviço Key Vault do Azure, terá de criar uma instância da classe, um URL do CertificateClient cofre e um objeto de credencial. Os exemplos apresentados neste documento utilizam um objeto de credencial com o nome DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Além disso, recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção.

Pode encontrar mais informações sobre as diferentes formas de autenticação e os tipos de credenciais correspondentes na documentação da Identidade do Azure.

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

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

Depois de estes serem importados, podemos ligar-nos 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);

Conceitos-chave

  • O cliente certificados é a interface principal para interagir com os métodos de API relacionados com certificados na API de Key Vault do Azure a partir de uma aplicação JavaScript. Uma vez inicializado, fornece um conjunto básico de métodos que podem ser utilizados para criar, ler, atualizar e eliminar certificados.
  • Uma versão de Certificado é uma versão de um certificado no Key Vault. Sempre que um utilizador atribui um valor a um nome de certificado exclusivo, é criada uma nova versão desse certificado. A obtenção de um certificado por um nome devolverá sempre o valor mais recente atribuído, a menos que seja fornecida uma versão específica à consulta.
  • A eliminação recuperável permite que os Key Vaults suportem a eliminação e remoção como dois passos separados, pelo que os certificados eliminados não são imediatamente perdidos. Isto só acontece se o Key Vault tiver a eliminação recuperável ativada.
  • Uma cópia de segurança de Certificado pode ser gerada a partir de qualquer certificado criado. Estas cópias de segurança são provenientes de dados binários e só podem ser utilizadas para regenerar um certificado eliminado anteriormente.

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

Por predefinição, este pacote utiliza a versão mais recente do serviço do Azure Key Vault, que é 7.1. A única outra versão suportada é 7.0. Pode alterar a versão do serviço que está a ser utilizada ao definir a opção serviceVersion no construtor 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 secções seguintes fornecem fragmentos de código que abrangem algumas das tarefas comuns com o Azure Key Vault Certificates. Os cenários abordados aqui consistem em:

Criar e definir um certificado

beginCreateCertificatecria um certificado a ser armazenado no Key Vault 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, também pode transmitir as seguintes propriedades num terceiro argumento com valores opcionais:

  • enabled: um valor booleano que determina se o certificado pode ou não ser utilizado.
  • tags: qualquer conjunto de valores-chave que pode ser utilizado para procurar 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 irá criar uma nova versão do mesmo certificado, que terá os atributos mais recentes fornecidos.

Uma vez que os Certificados demoram algum tempo a ser totalmente criados, beginCreateCertificate devolve um objeto poller que controla a Operação de Execução Prolongada subjacente de acordo com as nossas diretrizes: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

O poller recebido irá permitir-lhe obter o certificado criado ao chamar para poller.getResult(). Também pode aguardar até que a eliminação seja concluída, ao executar chamadas de serviço individuais até o certificado ser criado ou ao aguardar 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 forma de esperar até que o certificado seja assinado é efetuar chamadas individuais, da seguinte forma:

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 de Key Vault

A forma mais simples de ler certificados a partir do cofre é obter um certificado pelo nome. getCertificate obterá a versão mais recente do certificado, juntamente com a política do certificado. Opcionalmente, pode obter uma versão diferente do certificado ao ligar getCertificateVersion se especificar a versão. getCertificateVersion não devolve 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 as informações completas de um certificado

A estrutura do Azure Key Vault faz distinções nítidas entre Chaves, Segredos e Certificados. As funcionalidades certificados do serviço Key Vault foram concebidas para utilizar as suas capacidades de Chaves e Segredos. Vamos avaliar a composição de um Certificado de Key Vault:

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

Sabendo que a chave privada está armazenada num segredo de Key Vault, com o certificado público incluído, podemos recuperá-la com 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);

Tenha em atenção que, por predefinição, o tipo de conteúdo dos certificados é PKCS 12. Ao especificar o tipo de conteúdo do certificado, poderá recuperá-lo no formato PEM. Antes de mostrar como criar certificados PEM, vamos primeiro explorar como obter uma chave secreta PEM de um certificado PKCS 12 primeiro.

Com opensslo , pode obter o certificado público no formato PEM com o seguinte comando:

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

Também pode utilizar openssl para obter a chave privada, da seguinte forma:

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

Tenha em atenção que, em ambos os casos, o openssl irá pedir-lhe a palavra-passe utilizada para criar o certificado. O código de exemplo que utilizámos até agora não especificou uma palavra-passe, pelo que pode acrescentar -passin 'pass:' ao final de cada comando.

Certificados no formato PEM

Se quiser trabalhar com certificados no formato PEM, pode indicar ao serviço Key Vault do Azure para criar e gerir os seus certificados no formato PEM ao fornecer a contentType propriedade no momento da criação dos certificados.

O exemplo seguinte mostra como criar e obter as partes públicas e privadas de um certificado formatado PEM com o Key Vault clientes 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 atenção que o certificado público estará no mesmo blob de conteúdo que a sua chave privada. Pode utilizar os cabeçalhos PEM para extraí-los em conformidade.

Listar todos os certificados

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

Atualizar um certificado

Os atributos de certificado podem ser atualizados para uma versão de certificado existente com updateCertificate, 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 = 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 beginDeleteCertificate método configura um certificado para eliminação. Este processo ocorrerá em segundo plano assim que os recursos necessários estiverem disponíveis.

Se a eliminação recuperável estiver ativada para o Key Vault, esta operação só irá etiquetar o certificado como um certificado eliminado. Não é possível atualizar um certificado eliminado. Só podem ser lidas, recuperadas ou removidas.

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

Uma vez que a eliminação de um certificado não ocorrerá instantaneamente, é necessário algum tempo depois de o beginDeleteCertificate método ser chamado antes de o certificado eliminado estar disponível para ser lido, recuperado ou removido.

Iterating lists of certificates (Listas iterating de certificados)

Com o CertificateClient, pode obter e iterar todos os certificados num Cofre de Certificados, bem como através de todos os certificados eliminados e das versões de um certificado específico. Estão disponíveis os seguintes métodos de API:

  • listPropertiesOfCertificates listará todos os certificados não eliminados pelos respetivos nomes, apenas nas versões mais recentes.
  • listDeletedCertificates listará todos os certificados eliminados pelos respetivos nomes, apenas nas versões mais recentes.
  • listPropertiesOfCertificateVersions irá listar todas as versões de um certificado com base num nome de certificado.

O que pode ser utilizado 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 estes métodos devolverão todos os resultados disponíveis de uma só vez. Para os obter por páginas, adicione .byPage() logo após invocar o método de API que pretende utilizar, 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 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();

Resolução de problemas

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

Passos seguintes

Pode encontrar mais exemplos de código através das seguintes ligações:

Contribuir

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

Impressões