Clientcertificaat gebruiken voor verificatie in uw Node.js-web-app

Van toepassing op:Externe tenantsvan werknemers (meer informatie)

Microsoft Entra Externe ID ondersteunt twee typen verificatie voor vertrouwelijke clienttoepassingen; verificatie op basis van wachtwoorden (zoals clientgeheim) en verificatie op basis van certificaten. Voor een hoger beveiligingsniveau raden we u aan een certificaat (in plaats van een clientgeheim) te gebruiken als referentie in uw vertrouwelijke clienttoepassingen.

In productie moet u een certificaat aanschaffen dat is ondertekend door een bekende certificeringsinstantie en vervolgens Azure Key Vault gebruiken om certificaattoegang en levensduur te beheren. Voor testdoeleinden kunt u echter een zelfondertekend certificaat maken en uw apps configureren om ermee te verifiëren.

In dit artikel leert u hoe u een zelfondertekend certificaat genereert met behulp van Azure Key Vault in Azure Portal, OpenSSL of PowerShell. Als u al een clientgeheim hebt, leert u hoe u het veilig kunt verwijderen.

Indien nodig kunt u ook programmatisch een zelfondertekend certificaat maken met behulp van .NET-, Node.js-, Go-, Python- of Java-clientbibliotheken.

Vereisten

• Node.js.

• Visual Studio Code of een andere code-editor.

• Een externe tenant. Als u nog geen abonnement hebt, meldt u zich aan voor een gratis proefversie.

• OpenSSL of u kunt OpenSSL eenvoudig installeren in Windows via Chocolatey.

• Windows PowerShell - of Azure-abonnement.

Een zelfondertekend certificaat maken

Als u een bestaand zelfondertekend certificaat op uw lokale computer hebt, kunt u deze stap overslaan en doorgaan met het uploaden van het certificaat naar uw app-registratie.

Azure Key Vault - via Azure Portal

U kunt Azure Key Vault gebruiken om een zelfondertekend certificaat voor uw app te genereren. Met behulp van Azure Key Vault profiteert u van voordelen, zoals het toewijzen van een partnercertificeringsinstantie (CA) en het automatiseren van certificaatrotatie.

Als u een bestaand zelfondertekend certificaat in Azure Key Vault hebt en u dit wilt gebruiken zonder het te downloaden, slaat u deze stap over en gaat u verder met het gebruik van een zelfondertekend certificaat rechtstreeks vanuit Azure Key Vault. Gebruik anders de volgende stappen om uw certificaat te genereren

1. Volg de stappen in Set and retrieve a certificate from Azure Key Vault using the Azure Portal to create and download your certificate.

2. Nadat u het certificaat hebt gemaakt, downloadt u zowel het .cer-bestand als het PFX-bestand , zoals ciam-client-app-cert.cer en ciam-client-app-cert.pfx. Het bestand .cer bevat de openbare sleutel en is wat u uploadt naar uw Microsoft Entra-beheercentrum.

3. Voer in de terminal de volgende opdracht uit om de persoonlijke sleutel uit het PFX-bestand te extraheren. Wanneer u wordt gevraagd een wachtwoordzin te typen, drukt u op Enter als u er geen wilt instellen. Anders typt u een wachtwoordzin van uw keuze:

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

   Het ciam-client-app-cert.key-bestand is wat u in uw app gebruikt.

Windows PowerShell

1. Gebruik de stappen in Een zelfondertekend openbaar certificaat maken om uw toepassing te verifiëren. Zorg ervoor dat u uw openbare certificaat exporteert met de bijbehorende persoonlijke sleutel. Gebruik ciam-client-app-cert voor het certificateNamecertificaat.

2. Voer in de terminal de volgende opdracht uit om de persoonlijke sleutel uit het PFX-bestand te extraheren. Wanneer u wordt gevraagd uw wachtwoordzin in te voeren, typt u een wachtwoordzin van uw keuze:

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

Nadat u deze stappen hebt voltooid, hebt u een .cer-bestand en het .key-bestand , zoals ciam-client-app-cert.key en ciam-client-app-cert.cer. Het .key-bestand is wat u in uw app gebruikt. Het .cer-bestand is wat u uploadt naar uw Microsoft Entra-beheercentrum.

OpenSSL

Voer in de terminal de volgende opdracht uit. Wanneer u wordt gevraagd uw wachtwoordzin in te voeren, typt u een wachtwoordzin van uw keuze:

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

Nadat de opdracht is uitgevoerd, moet u een .crt en een .key-bestanden hebben, zoals ciam-client-app-cert.key en ciam-client-app-cert.crt. Het .key-bestand is wat u in uw app gebruikt. Het .cer-bestand is wat u uploadt naar uw Microsoft Entra-beheercentrum.

Certificaat uploaden naar uw app-registratie

Als u het certificaat van de client-app wilt gebruiken, moet u de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum koppelen aan het certificaat:

1. Meld u als toepassingsbeheerder aan bij het Microsoft Entra-beheercentrum.

2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen in het bovenste menu om vanuit het menu Mappen en abonnementen over te schakelen naar uw externe tenant.

3. Blader naar identiteitstoepassingen>> App-registraties.

4. Selecteer in de lijst met app-registratie de app die u aan het certificaat wilt koppelen, zoals ciam-client-app.

5. Selecteer onder Beheren de optie Certificaten en geheimen.

6. Selecteer Certificaten en selecteer vervolgens Certificaat uploaden.

7. Selecteer het pictogram Bestand selecteren en selecteer vervolgens het certificaat dat u wilt uploaden, zoals ciam-client-app-cert.pem of ciam-client-app-cert.cer of ciam-client-app-cert.crt.

8. Voor Beschrijving typt u een beschrijving, zoals het CIAM-client-app-certificaat en selecteert u Toevoegen om uw certificaat te uploaden. Zodra het certificaat is geüpload, worden de waarden voor vingerafdruk, begindatum en Verlopen weergegeven.

9. Noteer de vingerafdrukwaarde voor later gebruik wanneer u uw client-app configureert.

Als u al een clientgeheim voor uw toepassing hebt, moet u het verwijderen om te voorkomen dat een schadelijke toepassing wordt gebruikt voor het imiteren van uw toepassing:

1. Ga naar het tabblad Clientgeheimen en selecteer het pictogram Verwijderen .
2. Selecteer Ja in het pop-upvenster dat wordt weergegeven.

Uw Node.js-app configureren voor het gebruik van een certificaat

Zodra u uw app-registratie aan het certificaat hebt gekoppeld, moet u de app-code bijwerken om het certificaat te kunnen gebruiken:

1. Zoek het bestand met uw MSAL-configuratieobject, zoals msalConfig in authConfig.js, en werk het bij zodat het er ongeveer uitziet als de volgende code. Als er een clientgeheim aanwezig is, moet u het volgende verwijderen:

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

   Vervang de tijdelijke aanduidingen in uw code:

   • Add_Passphrase_Here met de wachtwoordzin die u hebt gebruikt om uw persoonlijke sleutel te versleutelen.

   • YOUR_CERT_THUMBPRINT met de vingerafdrukwaarde die u eerder hebt genoteerd.

   • PATH_TO_YOUR_PRIVATE_KEY_FILE met het bestandspad naar uw persoonlijke sleutelbestand.

   • Enter_the_Application_Id_Here met de toepassings-id (client) van de app die u eerder hebt geregistreerd.

   • Enter_the_Tenant_Subdomain_Here en vervang het door het subdomein Directory (tenant). Als uw primaire tenantdomein bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u uw tenantnaam niet hebt, leest u de details van uw tenant.

   We hebben de sleutel versleuteld (we raden u aan dit te doen), dus we moeten deze ontsleutelen voordat we deze doorgeven aan het MSAL-configuratieobject.

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

2. Gebruik de stappen in Uitvoeren en test de web-app om uw app te testen.

Een zelfondertekend certificaat rechtstreeks vanuit Azure Key Vault gebruiken

U kunt uw bestaande certificaat rechtstreeks vanuit Azure Key Vault gebruiken:

1. Zoek het bestand met uw MSAL-configuratieobject, zoals msalConfig in authConfig.js, en verwijder vervolgens de clientSecret eigenschap:

   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. Installeer Azure CLI en typ vervolgens in uw console de volgende opdracht om u aan te melden:

   az login --tenant YOUR_TENANT_ID
   

   Vervang de tijdelijke aanduiding YOUR_TENANT_ID door de map-id (tenant) die u eerder hebt gekopieerd.

3. Typ op de console de volgende opdracht om de vereiste pakketten te installeren:

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

4. Gebruik in uw client-app de volgende code om te genereren thumbprint en 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();        
   

   Vervang de tijdelijke aanduidingen in uw code:

   • ENTER_YOUR_KEY_VAULT_URL met uw Azure Key Vault-URL.

   • ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT met de naam van uw certificaat in Azure Key Vault.

5. Gebruik de thumbprint en privateKey waarden om uw configuratie bij te werken:

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

6. Ga vervolgens verder met het instantiëren van uw vertrouwelijke client, zoals wordt weergegeven in de getMsalInstance methode:

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

7. Gebruik de stappen in Uitvoeren en test de web-app om uw app te testen.

Volgende stappen

Leer hoe u het volgende doet:

• Meld u aan bij gebruikers en roep een API aan in uw eigen Node.js webtoepassing.