Usar o certificado do cliente para autenticação em seu aplicativo Web Node.js

Aplica-se a: Locatários da força de trabalho Locatários externos (saiba mais)

A ID externa do Microsoft Entra dá suporte a dois tipos de autenticação para aplicativos cliente confidenciais: autenticação baseada em senha (como segredo do cliente) e autenticação baseada em certificado. Para um nível mais alto de segurança, recomendamos usar um certificado (em vez de um segredo do cliente) como uma credencial em seus aplicativos cliente confidenciais.

Na produção, você deve comprar um certificado assinado por uma autoridade de certificação conhecida e usar o Azure Key Vault para gerenciar o acesso e o tempo de vida do certificado. No entanto, para fins de teste, você pode criar um certificado autoassinado e configurar seus aplicativos para autenticar-se com ele.

Neste artigo, você aprenderá a gerar um certificado autoassinado usando o Azure Key Vault no portal do Azure, no OpenSSL ou no PowerShell. Se você já possui um segredo do cliente, aprenderá como excluí-lo de forma segura.

Quando necessário, você também pode criar um certificado autoassinado programaticamente usando bibliotecas de cliente .NET, Node.js, Go, Python ou Java.

Pré-requisitos

• Node.js.

• Visual Studio Code ou outro editor de código.

• Um locatário externo. Caso ainda não tenha uma, inscreva-se em uma avaliação gratuita.

• OpenSSL ou você pode instalar facilmente o OpenSSL no Windows por meio do Chocolatey.

• Windows PowerShell ou assinatura do Azure.

Criará um certificado autoassinado

Se você tiver um certificado autoassinado em seu computador local, poderá ignorar esta etapa e prosseguir para Carregar certificado para o registro do aplicativo.

Azure Key Vault – via portal do Azure

Você pode usar o Azure Key Vault para gerar um certificado autoassinado para seu aplicativo. Usando o Azure Key Vault, você desfruta de benefícios, como atribuir uma AC (Autoridade de Certificação) de parceiro e automatizar a rotação de certificados.

Se você tiver um certificado autoassinado existente no Azure Key Vault e quiser usá-lo sem baixá-lo, ignore esta etapa e vá para Usar um certificado autoassinado diretamente do Azure Key Vault. Caso contrário, use as etapas a seguir para gerar seu certificado

1. Siga as etapas em Definir e recuperar um certificado do Azure Key Vault usando o portal do Azure para criar e baixar seu certificado.

2. Depois de criar seu certificado, baixe o arquivo .cer e o arquivo .pfx, como ciam-client-app-cert.cer e ciam-client-app-cert.pfx. O arquivo .cer contém a chave pública e é o que você carrega no centro de administração do Microsoft Entra.

3. No terminal, execute o comando a seguir para extrair a chave privada do arquivo .pfx. Quando solicitado a digitar uma senha, basta pressionar Enter se você não quiser definir uma. Caso contrário, digite uma senha de sua escolha:

   openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key
   

   O arquivo ciam-client-app-cert.key é o que você usa em seu aplicativo.

Windows PowerShell

1. Siga as etapas em Criar um certificado público autoassinado para autenticar seu aplicativo. Exporte seu certificado público com sua chave privada. Para o certificateName, use ciam-client-app-cert.

2. No terminal, execute o comando a seguir para extrair a chave privada do arquivo .pfx. Quando solicitado a digitar sua senha, digite uma frase secreta de sua escolha:

   openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key
   

Depois de concluir essas etapas, você deverá ter um arquivo .cer e o arquivo .key, como ciam-client-app-cert.key e ciam-client-app-cert.cer. O arquivo .key é o que você usa em seu aplicativo. O arquivo .cer é o que você carrega no centro de administração do Microsoft Entra.

OpenSSL

Em seu terminal, execute o seguinte comando: Quando solicitado a digitar sua senha, digite uma frase secreta de sua escolha:

openssl req -x509 -newkey rsa:2048 -keyout ciam-client-app-cert.key -out ciam-client-app-cert.crt -subj "/CN=ciamclientappcert.com"

Depois que o comando concluir a execução, você deverá ter arquivos .crt e .key, como ciam-client-app-cert.key e ciam-client-app-cert.crt. O arquivo .key é o que você usa em seu aplicativo. O arquivo .cer é o que você carrega no centro de administração do Microsoft Entra.

Carregar certificado no registro do aplicativo

Para usar o certificado do aplicativo cliente, você precisa associar o aplicativo registrado no centro de administração do Microsoft Entra ao certificado:

1. Entre no Centro de administração do Microsoft Entra pelo menos como um Administrador de Aplicativo.

2. Se tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o seu locatário externo no menu Diretórios + assinaturas.

3. Navegue até Identidade>Aplicativos>Registros do aplicativo.

4. Na lista de registro do aplicativo, selecione o aplicativo que você deseja associar ao certificado, como ciam-client-app.

5. Em Gerenciar, selecione Certificados e segredos.

6. Selecione Certificados e selecione Carregar certificado.

7. Selecione o ícone Selecionar um arquivo de arquivo e selecione o certificado que você deseja carregar, como ciam-client-app-cert.pem ou ciam-client-app-cert.cer ou ciam-client-app-cert.crt.

8. Para Descrição, digite uma descrição, como certificado de aplicativo cliente CIAM, e selecione Adicionar para carregar seu certificado. Após o carregamento do certificado, os valores de Impressão digital, Data de início e Expiração são exibidos.

9. Registre o valor da Impressão digital para uso posterior ao configurar seu aplicativo cliente.

Se você já tem um segredo do cliente configurado para o seu aplicativo, é necessário excluí-lo para evitar que um aplicativo mal-intencionado se passe pelo seu:

1. Vá até a guia Segredos do Cliente e selecione o ícone Excluir.
2. Na janela pop-up que aparece, selecione Sim.

Configurar seu aplicativo Node.js para usar o certificado

Depois de associar o registro do aplicativo ao certificado, você precisará atualizar o código do aplicativo para começar a usar o certificado:

1. Localize o arquivo que contém seu objeto de configuração da MSAL, como por exemplo msalConfig em authConfig.js, e então atualize-o para que fique semelhante ao código a seguir. Se você tiver um segredo do cliente presente, certifique-se de removê-lo:

   require('dotenv').config();
   const fs = require('fs'); //// import the fs module for reading the key file
   const crypto = require('crypto');
   const TENANT_SUBDOMAIN = process.env.TENANT_SUBDOMAIN || 'Enter_the_Tenant_Subdomain_Here';
   const REDIRECT_URI = process.env.REDIRECT_URI || 'http://localhost:3000/auth/redirect';
   const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI || 'http://localhost:3000';
   
   const privateKeySource = fs.readFileSync('PATH_TO_YOUR_PRIVATE_KEY_FILE')
   
   const privateKeyObject = crypto.createPrivateKey({
       key: privateKeySource,
       passphrase: 'Add_Passphrase_Here',
       format: 'pem'
   });
   
   const privateKey = privateKeyObject.export({
       format: 'pem',
       type: 'pkcs8'
   });
   
   /**
    * Configuration object to be passed to MSAL instance on creation.
    * For a full list of MSAL Node configuration parameters, visit:
    * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
    */
       const msalConfig = {
           auth: {
               clientId: process.env.CLIENT_ID || 'Enter_the_Application_Id_Here', // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
               authority: process.env.AUTHORITY || `https://${TENANT_SUBDOMAIN}.ciamlogin.com/`, 
               clientCertificate: {
                   thumbprint: "YOUR_CERT_THUMBPRINT", // replace with thumbprint obtained during step 2 above
                   privateKey: privateKey
               }
           },
           //... Rest of code in the msalConfig object
       };
   
   module.exports = {
       msalConfig,
       REDIRECT_URI,
       POST_LOGOUT_REDIRECT_URI,
       TENANT_SUBDOMAIN
   };
   

   No código, substitua os espaços reservados:

   • Add_Passphrase_Here com a senha usada para criptografar sua chave privada.

   • YOUR_CERT_THUMBPRINT com o valor de Impressão digital que você registrou anteriormente.

   • PATH_TO_YOUR_PRIVATE_KEY_FILE com o caminho do arquivo para o arquivo de chave privada.

   • Enter_the_Application_Id_Here com o ID do aplicativo (cliente) referente ao aplicativo registrado anteriormente.

   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio diretório (locatário). Por exemplo, se o domínio primário do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.

   Criptografamos a chave (recomendamos que você faça isso), portanto, precisamos descriptografá-la antes de passá-la para o objeto de configuração MSAL.

   //...
   const privateKeyObject = crypto.createPrivateKey({
       key: privateKeySource,
       passphrase: 'Add_Passphrase_Here',
       format: 'pem'
   });
   
   const privateKey = privateKeyObject.export({
       format: 'pem',
       type: 'pkcs8'
   });
   //...
   

2. Use as etapas em Executar e testar o aplicativo Web para testar seu aplicativo.

Usar um certificado autoassinado diretamente do Azure Key Vault

Você pode usar seu certificado existente diretamente do Azure Key Vault:

1. Localize o arquivo que contém seu objeto de configuração da MSAL, como por exemplo msalConfig em authConfig.js, e então remova a propriedade clientSecret:

   const msalConfig = {
       auth: {
           clientId: process.env.CLIENT_ID || 'Enter_the_Application_Id_Here', // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
           authority: process.env.AUTHORITY || `https://${TENANT_SUBDOMAIN}.ciamlogin.com/`, 
       },
       //...
   };
   

2. Instale a CLI do Azure e, no console, digite o seguinte comando para entrar:

   az login --tenant YOUR_TENANT_ID
   

   Substitua o espaço reservado YOUR_TENANT_ID pela ID do Diretório (locatário) que você copiou antes.

3. No console, digite o seguinte comando para instalar os pacotes necessários:

   npm install --save @azure/identity @azure/keyvault-certificates @azure/keyvault-secrets
   

4. No aplicativo cliente, use o código a seguir para gerar thumbprint e privateKey;

   const identity = require("@azure/identity");
   const keyvaultCert = require("@azure/keyvault-certificates");
   const keyvaultSecret = require('@azure/keyvault-secrets');
   
   const KV_URL = process.env["KEY_VAULT_URL"] || "ENTER_YOUR_KEY_VAULT_URL"
   const CERTIFICATE_NAME = process.env["CERTIFICATE_NAME"] || "ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT";
   
   // Initialize Azure SDKs
   const credential = new identity.DefaultAzureCredential();
   const certClient = new keyvaultCert.CertificateClient(KV_URL, credential);
   const secretClient = new keyvaultSecret.SecretClient(KV_URL, credential);
   
   async function getKeyAndThumbprint() {
   
       // Grab the certificate thumbprint
       const certResponse = await certClient.getCertificate(CERTIFICATE_NAME).catch(err => console.log(err));
       const thumbprint = certResponse.properties.x509Thumbprint.toString('hex')
   
       // When you upload a certificate to Key Vault, a secret containing your private key is automatically created
       const secretResponse = await secretClient.getSecret(CERTIFICATE_NAME).catch(err => console.log(err));;
   
       // secretResponse contains both public and private key, but we only need the private key
       const privateKey = secretResponse.value.split('-----BEGIN CERTIFICATE-----\n')[0]
   }
   
   getKeyAndThumbprint();        
   

   No código, substitua os espaços reservados:

   • ENTER_YOUR_KEY_VAULT_URL com o URL do Azure Key Vault.

   • ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT com o nome do certificado no Azure Key Vault.

5. Use os valores thumbprint e privateKey para atualizar sua configuração:

   let clientCert = {
       thumbprint: thumbprint, 
       privateKey: privateKey,
   };
   
   msalConfig.auth.clientCertificate = clientCert; //For this to work, you can't declares your msalConfig using const modifier 
   

6. Em seguida, prossiga para instanciar seu cliente confidencial, conforme mostrado no método getMsalInstance:

   class AuthProvider {
       //...
       getMsalInstance(msalConfig) {
           return new msal.ConfidentialClientApplication(msalConfig);
       }
       //...
   }
   

7. Use as etapas em Executar e testar o aplicativo Web para testar seu aplicativo.

Próximas etapas

Saiba como:

• Conecte usuários e chame uma API em seu aplicativo Web Node.js.