Guia de início rápido: biblioteca de cliente de certificado do Azure Key Vault para JavaScript

  • Artigo

Introdução à biblioteca de cliente de certificado do Azure Key Vault para JavaScript. O Azure Key Vault é um serviço de nuvem que fornece um armazenamento seguro para certificados. Pode armazenar chaves, palavras-passe, certificados e outros segredos em segurança. Os cofres de chaves do Azure podem ser criados e geridos através do portal do Azure. Neste guia de início rápido, você aprenderá a criar, recuperar e excluir certificados de um cofre de chaves do Azure usando a biblioteca de cliente JavaScript

Recursos da biblioteca do cliente Key Vault:

Documentação | de referência da API Pacote de código-fonte | da biblioteca (npm)

Para obter mais informações sobre o Key Vault e certificados, consulte:

Pré-requisitos

Este início rápido pressupõe que você esteja executando a CLI do Azure.

Iniciar sessão no Azure

  1. Execute o comando login.

    az login

    Se a CLI puder abrir seu navegador padrão, ela fará isso e carregará uma página de entrada do Azure.

    Caso contrário, abra uma página do navegador e https://aka.ms/devicelogin insira o código de autorização exibido no seu terminal.

  2. Inicie sessão com as credenciais da sua conta no browser.

Criar novo aplicativo Node.js

Crie um aplicativo Node.js que use seu cofre de chaves.

  1. Em um terminal, crie uma pasta chamada key-vault-node-app e altere para essa pasta:

    mkdir key-vault-node-app && cd key-vault-node-app

  2. Inicialize o projeto Node.js:

    npm init -y

Instalar pacotes Key Vault

  1. Usando o terminal, instale a biblioteca de segredos do Azure Key Vault, @azure/keyvault-certificates para Node.js.

    npm install @azure/keyvault-certificates

  2. Instale a biblioteca de cliente do Azure Identity, @azure/identity, para autenticar em um Cofre de Chaves.

    npm install @azure/identity

Conceder acesso ao seu cofre de chaves

Para conceder permissões ao seu aplicativo para seu cofre de chaves por meio do RBAC (Controle de Acesso Baseado em Função), atribua uma função usando o comando az role assignment create da CLI do Azure.

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Substitua <app-id>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos seus valores reais. <app-id> é a ID do Aplicativo (cliente) do seu aplicativo registrado no Azure AD.

Definir variáveis de ambiente

Este aplicativo está usando o nome do cofre de chaves como uma variável de ambiente chamada KEY_VAULT_NAME.

set KEY_VAULT_NAME=<your-key-vault-name>

Autenticar e criar um cliente

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar o método DefaultAzureCredential fornecido pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Neste início rápido, DefaultAzureCredential autentica-se no cofre de chaves usando as credenciais do usuário de desenvolvimento local conectado à CLI do Azure. Quando o aplicativo é implantado no Azure, o mesmo DefaultAzureCredential código pode descobrir e usar automaticamente uma identidade gerenciada atribuída a um Serviço de Aplicativo, Máquina Virtual ou outros serviços. Para obter mais informações, consulte Visão geral da identidade gerenciada.

Neste código, o nome do cofre de chaves é usado para criar o URI do cofre de chaves, no formato https://<your-key-vault-name>.vault.azure.net. Para obter mais informações sobre como autenticar no cofre de chaves, consulte o Guia do desenvolvedor.

Exemplo de código

Esse código usa as seguintes classes e métodos do Key Vault Certificate:

Configurar a estrutura do aplicativo

  1. Crie um novo arquivo de texto e cole o código a seguir no arquivo index.js .

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

async function main() {
  // If you're using MSI, DefaultAzureCredential should "just work".
  // Otherwise, DefaultAzureCredential expects the following three environment variables:
  // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
  // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
  // - AZURE_CLIENT_SECRET: The client secret for the registered application
  const credential = new DefaultAzureCredential();

  const keyVaultName = process.env["KEY_VAULT_NAME"];
  if(!keyVaultName) throw new Error("KEY_VAULT_NAME is empty");
  const url = "https://" + keyVaultName + ".vault.azure.net";

  const client = new CertificateClient(url, credential);

  const uniqueString = new Date().getTime();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  const pendingCertificate = createPoller.getResult();
  console.log("Certificate: ", pendingCertificate);

  // To read a certificate with their policy:
  let certificateWithPolicy = await client.getCertificate(certificateName);
  // Note: It will always read the latest version of the certificate.

  console.log("Certificate with policy:", certificateWithPolicy);

  // To read a certificate from a specific version:
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version
  );
  // Note: It will not retrieve the certificate's policy.
  console.log("Certificate from a specific version:", certificateFromVersion);

  const updatedCertificate = await client.updateCertificateProperties(certificateName, "", {
    tags: {
      customTag: "value"
    }
  });
  console.log("Updated certificate:", updatedCertificate);

  // Updating the certificate's policy:
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyOtherCert"
  });
  certificateWithPolicy = await client.getCertificate(certificateName);
  console.log("updatedCertificate certificate's policy:", certificateWithPolicy.policy);

  // delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  console.log("Recovery Id: ", deletedCertificate.recoveryId);
  console.log("Deleted Date: ", deletedCertificate.deletedOn);
  console.log("Scheduled Purge Date: ", deletedCertificate.scheduledPurgeDate);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Executar o exemplo de aplicação

  1. Execute a aplicação:

    node index.js

  2. Os métodos create e get retornam um objeto JSON completo para o certificado:

    {
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME.vault.azure.net/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME.vault.azure.net",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Integração com a configuração do aplicativo

O SDK do Azure fornece um método auxiliar, parseKeyVaultCertificateIdentifier, para analisar a ID de certificado do Cofre da Chave fornecida, que é necessária se você usar referências de Configuração do Aplicativo ao Cofre da Chave. A Configuração do Aplicativo armazena o ID do certificado do Cofre da Chave. Você precisa do método parseKeyVaultCertificateIdentifier para analisar essa ID para obter o nome do certificado. Depois de ter o nome do certificado, você pode obter o certificado atual usando o código deste início rápido.

Próximos passos

Neste início rápido, você criou um cofre de chaves, armazenou um certificado e recuperou esse certificado. Para saber mais sobre o Key Vault e como integrá-lo com seus aplicativos, continue nestes artigos.