Usare il certificato client per l'autenticazione nell'app Web Node.js

Si applica a: Tenant della forza lavoro Tenant esterni (altre informazioni)

Microsoft Entra External ID supporta due tipi di autenticazione per le applicazioni client riservate: l'autenticazione basata su password (ad esempio il segreto client) e l'autenticazione basata su certificati. Per un livello di sicurezza superiore, è consigliabile usare un certificato (anziché un segreto client) come credenziale nelle applicazioni client riservate.

Nell'ambiente di produzione è necessario acquistare un certificato firmato da un'autorità di certificazione nota, quindi usare Azure Key Vault per gestire l'accesso e la durata dei certificati. Tuttavia, a scopo di test, è possibile creare un certificato autofirmato e configurare le app per l'autenticazione.

Questo articolo illustra come generare un certificato autofirmato usando Azure Key Vault nel portale di Azure, OpenSSL o PowerShell. Se si ha già un segreto client, si apprenderà come eliminarlo in modo sicuro.

Quando necessario, è anche possibile creare un certificato autofirmato a livello di codice usando .NET, Node.js, Go, Python o le librerie client Java.

Prerequisiti

• Node.js.

• Visual Studio Code o un altro editor di codice.

• Un tenant esterno. Se non se ne dispone già, iscriversi per ottenere una versione di valutazione gratuita.

• OpenSSL o è possibile installare facilmente OpenSSL in Windows tramite Chocolatey.

• Sottoscrizione di Windows PowerShell o Azure.

Creare un certificato autofirmato

Se nel computer locale è presente un certificato autofirmato, è possibile ignorare questo passaggio, quindi passare a Carica certificato nella registrazione dell'app.

Azure Key Vault - tramite il portale di Azure

È possibile usare Azure Key Vault per generare un certificato autofirmato per l'app. L'uso di Azure Key Vault offre dei vantaggi, ad esempio l'assegnazione di un'autorità di certificazione (CA) partner e l'automazione della rotazione dei certificati.

Se si ha un certificato autofirmato esistente in Azure Key Vault e si vuole usarlo senza scaricarlo, ignorare questo passaggio, quindi passare a Usare un certificato autofirmato direttamente da Azure Key Vault. In caso contrario, usare la procedura seguente per generare il certificato

1. Seguire la procedura descritta in Impostare e recuperare un certificato da Azure Key Vault usando il portale di Azure per creare e scaricare il certificato.

2. Dopo aver creato il certificato, scaricare sia il file .cer che il file pfx, ad esempio ciam-client-app-cert.cer e ciam-client-app-cert.pfx. Il file .cer contiene la chiave pubblica ed è ciò che si carica nell'interfaccia di amministrazione di Microsoft Entra.

3. Nel terminale eseguire il comando seguente per estrarre la chiave privata dal file pfx. Quando viene richiesto di digitare una pass phrase, è sufficiente premere INVIO se non se ne vuole impostare una. In caso contrario, digitare una pass phrase di propria scelta:

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

   Il file ciam-client-app-cert.key è quello che usi nell'app.

Windows PowerShell

1. Usare la procedura descritta in Creare un certificato pubblico autofirmato per autenticare l'applicazione. Assicurarsi di esportare il certificato pubblico con la relativa chiave privata. Per certificateName, usare ciam-client-app-cert.

2. Nel terminale eseguire il comando seguente per estrarre la chiave privata dal file pfx. Quando viene richiesto di digitare la pass phrase, digitare una pass phrase di propria scelta:

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

Dopo aver completato questi passaggi, è necessario disporre di un file .cer e del file .key, ad esempio ciam-client-app-cert.key e ciam-client-app-cert.cer. Il file .key è quello che si usa nella propria app. Il file .cer è quello che si carica nell'interfaccia di amministrazione di Microsoft Entra.

OpenSSL

Nel terminale eseguire il comando seguente. Quando viene richiesto di digitare la pass phrase, digitare una pass phrase di propria scelta:

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

Al termine dell'esecuzione del comando, è necessario disporre di un file .crt e di un file .key, ad esempio ciam-client-app-cert.key e ciam-client-app-cert.crt. Il file .key è quello che si usa nella propria app. Il file .cer è quello che si carica nell'interfaccia di amministrazione di Microsoft Entra.

Caricare il certificato nella registrazione dell'app

Per usare il certificato dell'app client, è necessario associare l'app registrata nell'interfaccia di amministrazione di Microsoft Entra al certificato:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come un Amministratore di applicazioni.

2. Se si ha accesso a più tenant, usare l'icona impostazioni nel menu in alto per passare al tenant esterno dal menu Directory e sottoscrizioni.

3. Passare a Identità>Applicazioni>Registrazioni app.

4. Nell'elenco di registrazione dell'app selezionare l'app che si vuole associare al certificato, ad esempio ciam-client-app.

5. In Gestisci, selezionare Certificati e segreti.

6. Selezionare Certificati e quindi Carica certificato.

7. Selezionare l'icona del file Seleziona un file, quindi selezionare il certificato da caricare, ad esempio ciam-client-app-cert.pem o ciam-client-app-cert.cer o ciam-client-app-cert.crt.

8. Per Descrizione, digitare una descrizione, ad esempio il certificato dell'app client CIAM, quindi selezionare Aggiungi per caricare il certificato. Dopo il caricamento del certificato, vengono visualizzati i valori Identificazione personale, Data di inizio e Scadenza.

9. Registrare il valore identificazione personale da usare in un secondo momento quando si configura l'app client.

Se è già disponibile un segreto client per l'applicazione, è necessario eliminarlo per evitare un'applicazione dannosa per la rappresentazione dell'applicazione:

1. Passare alla scheda Segreti client e selezionare l'icona Elimina.
2. Nella finestra popup visualizzata selezionare Sì.

Configurare l'app Node.js per l'uso del certificato

Dopo aver associato la registrazione dell'app al certificato, è necessario aggiornare il codice dell'app per iniziare a usare il certificato:

1. Individuare il file contenente l'oggetto di configurazione MSAL, ad esempio msalConfig in authConfig.js, quindi aggiornarlo in modo che sia simile al codice seguente. Se è presente un segreto client, assicurarsi di rimuoverlo:

   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
   };
   

   Nel codice, sostituire i segnaposto:

   • Add_Passphrase_Here con la pass phrase usata per crittografare la chiave privata.

   • YOUR_CERT_THUMBPRINT con il valore identificazione personale registrato in precedenza.

   • PATH_TO_YOUR_PRIVATE_KEY_FILE con il percorso del file della chiave privata.

   • Enter_the_Application_Id_Here con l'ID applicazione (client) dell'app registrata in precedenza.

   • Enter_the_Tenant_Subdomain_Here e sostituire con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se non si ha il nome del tenant, vedere come leggere i dettagli del tenant.

   La chiave è stata crittografata (è consigliabile farlo), quindi è necessario decrittografarla prima di passarla all'oggetto di configurazione MSAL.

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

2. Usare la procedura descritta in Eseguire e testare l'app Web per testare l'app.

Usare un certificato autofirmato direttamente da Azure Key Vault

È possibile usare il certificato esistente direttamente da Azure Key Vault:

1. Individuare il file contenente l'oggetto di configurazione MSAL, ad esempio msalConfig in authConfig.js, quindi rimuovere la proprietà 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. Installare l’interfaccia della riga di comando di Azure, quindi nella console digitare il comando seguente per accedere:

   az login --tenant YOUR_TENANT_ID
   

   Sostituire il segnaposto YOUR_TENANT_ID con l'ID directory (tenant) copiato in precedenza.

3. Nella console digitare il comando seguente per installare i pacchetti necessari:

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

4. Nell'app client usare il codice seguente per generare 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();        
   

   Nel codice, sostituire i segnaposto:

   • ENTER_YOUR_KEY_VAULT_URL con l'URL di Azure Key Vault.

   • ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT con il nome del certificato in Azure Key Vault.

5. Usare i valori thumbprint e privateKey per aggiornare la configurazione:

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

6. Passare quindi a creare un'istanza del client riservato, come illustrato nel metodo getMsalInstance:

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

7. Usare la procedura descritta in Eseguire e testare l'app Web per testare l'app.

Passaggi successivi

Scopri come:

• Accedere agli utenti e chiamare un'API nella propria applicazione Web Node.js.