Usar certificado de 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)

O Microsoft Entra External ID suporta 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 o uso de 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, em seguida, usar o Cofre da Chave do Azure 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 autenticação com ele.

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

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. Se ainda não tiver uma, inscreva-se para uma avaliação gratuita.

• OpenSSL ou você pode facilmente instalar OpenSSL no Windows via Chocolatey.

• Assinatura do Windows PowerShell ou do Azure.

Criar um certificado autoassinado

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

Azure Key Vault - através do portal do Azure

Você pode usar o Azure Key Vault para gerar um certificado autoassinado para seu aplicativo. Ao usar o Cofre da Chave do Azure, você desfruta de benefícios, como a atribuição de uma Autoridade de Certificação (CA) parceira e a automação da rotação de certificados.

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

1. Siga as etapas em Definir e recuperar um certificado do Cofre da Chave do Azure 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 ficheiro .cer contém a chave pública e é o que carrega para o centro de administração do Microsoft Entra.

3. No seu terminal, execute o seguinte comando para extrair a chave privada do ficheiro .pfx . Quando solicitado a digitar uma frase secreta, basta pressionar a tecla Enter se não quiser definir uma. Caso contrário, digite uma frase secreta 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. Use as etapas em Criar um certificado público autoassinado para autenticar seu aplicativo. Certifique-se de exportar seu certificado público com sua chave privada. Para o certificateName, use ciam-client-app-cert.

2. No seu terminal, execute o seguinte comando para extrair a chave privada do ficheiro .pfx . Quando lhe for pedido para escrever a sua frase secreta, escreva uma frase secreta à sua escolha:

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

Depois de concluir essas etapas, você deve 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 ficheiro .cer é o que carrega para o centro de administração do Microsoft Entra.

OpenSSL

No seu terminal, execute o seguinte comando. Quando lhe for pedido para escrever a sua frase secreta, escreva uma frase secreta à 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 terminar a execução, você deve ter um arquivo .crt e um arquivo .key , como ciam-client-app-cert.key e ciam-client-app-cert.crt. O arquivo .key é o que você usa em seu aplicativo. O ficheiro .cer é o que carrega para o centro de administração do Microsoft Entra.

Carregar certificado para o registo da aplicação

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 como pelo menos um Administrador de Aplicativos.

2. Se tiver acesso a vários inquilinos, utilize o ícone Definições no menu superior para mudar para o inquilino externo a partir do menu Diretórios + subscrições.

3. Navegue até Registros do aplicativo Identity>Applications>.

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 & segredos.

6. Selecione Certificados e, em seguida, selecione Carregar certificado.

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

8. Em Descrição, digite uma descrição, como certificado de aplicativo cliente CIAM, e selecione Adicionar para carregar seu certificado. Depois que o certificado for carregado, os valores Impressão digital, Data de início e Expira serão exibidos.

9. Registre o valor de impressão digital para uso posterior ao configurar seu aplicativo cliente.

Se você já tiver um segredo de cliente para seu aplicativo, precisará excluí-lo para evitar um aplicativo mal-intencionado para se passar por seu aplicativo:

1. Vá para a guia Segredos do cliente e selecione o ícone Excluir .
2. Na janela pop-up apresentada, selecione Sim.

Configurar seu aplicativo Node.js para usar o certificado

Depois de associar o registro do aplicativo ao certificado, você precisa 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 MSAL, como msalConfig no authConfig.js e, em seguida, atualize-o para ter uma aparência 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 frase secreta que utilizou para encriptar a 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 ficheiro para o ficheiro de chave privada.

   • Enter_the_Application_Id_Here com o ID do aplicativo (cliente) do aplicativo que você registrou anteriormente.

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

   Nós criptografamos a chave (recomendamos que você faça isso), então temos que 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 Cofre da Chave do Azure

Você pode usar seu certificado existente diretamente do Cofre da Chave do Azure:

1. Localize o arquivo que contém o objeto de configuração do MSAL, como msalConfig no authConfig.js, e remova a clientSecret propriedade:

   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, em seguida, 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) copiada anteriormente.

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. Em seu aplicativo cliente, use o seguinte código 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 seu certificado no Cofre da Chave do Azure.

5. Use os thumbprint valores 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 como mostrado no getMsalInstance método:

   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óximos passos

Aprenda a:

• Inicie sessão de utilizadores e chame uma API na sua própria aplicação Web Node.js.