Freigeben über

Verwenden eines Clientzertifikats für die Authentifizierung in Ihrer Node.js-Web-App

  • Artikel

Gilt für: Weißer Kreis mit grauem X. Mitarbeitermandanten Grüner Kreis mit weißem Häkchen. Externe Mandanten (weitere Informationen)

Microsoft Entra External ID unterstützt zwei Arten der Authentifizierung für vertrauliche Clientanwendungen: kennwortbasierte Authentifizierung (z. B. mit einem geheimen Clientschlüssel) und zertifikatbasierte Authentifizierung. Für eine höhere Sicherheitsstufe empfehlen wir die Verwendung eines Zertifikats (anstelle eines geheimen Clientschlüssels) als Anmeldeinformationen in vertraulichen Clientanwendungen.

Für die Produktionsumgebung sollten Sie ein Zertifikat erwerben, das von einer bekannten Zertifizierungsstelle signiert ist, dann Azure Key Vault verwenden, mit dem Sie den Zugriff auf Zertifikate und deren Lebensdauer verwalten können. Zu Testzwecken können Sie jedoch ein selbstsigniertes Zertifikat erstellen und Ihre Anwendungen so konfigurieren, dass sie sich damit authentifizieren können.

In diesem Artikel erfahren Sie, wie Sie ein selbstsigniertes Zertifikat mithilfe von Azure Key Vault auf dem Azure-Portal, OpenSSL oder PowerShell generieren. Wenn Sie bereits über einen geheimen Clientschlüssel verfügen, erfahren Sie, wie Sie ihn sicher löschen.

Bei Bedarf können Sie ein selbstsigniertes Zertifikat auch programmgesteuert mithilfe von .NET-, Node.js-, Go-, Python- oder Java-Clientbibliotheken erstellen.

Voraussetzungen

Erstellen eines selbstsignierten Zertifikats

Wenn Sie auf Ihrem lokalen Computer über ein selbstsigniertes Zertifikat verfügen, können Sie diesen Schritt überspringen und dann mit dem Schritt Zertifikat in Ihre Anwendungsregistrierung hochladen fortfahren.

Sie können Azure Key Vault verwenden, um ein selbstsigniertes Zertifikat für Ihre Anwendung zu generieren. Durch die Verwendung von Azure Key Vault profitieren Sie von Vorteilen, z. B. das Zuweisen einer Partnerzertifizierungsstelle (Certificate Authority, CA) und die Automatisierung der Zertifikatrotation.

Wenn Sie in Azure Key Vault über ein vorhandenes selbstsigniertes Zertifikat verfügen und es ohne Herunterladen verwenden möchten, überspringen Sie diesen Schritt, und fahren Sie mit dem Schritt Verwenden eines selbstsignierten Zertifikats direkt aus Azure Key Vault fort. Führen Sie andernfalls die folgenden Schritte aus, um das Zertifikat zu generieren.

  1. Führen Sie die Schritte unter Festlegen und Abrufen eines Zertifikats aus Azure Key Vault mithilfe des Azure-Portals zum Erstellen und Herunterladen des Zertifikats aus.

  2. Nachdem Sie das Zertifikat erstellt haben, laden Sie sowohl die .cer-Datei als auch die .pfx-Datei herunter, z. B. ciam-client-app-cert.cer und ciam-client-app-cert.pfx. Die .cer-Datei enthält den öffentlichen Schlüssel. Diesen laden Sie in Ihr Microsoft Entra Admin Center hoch.

  3. Führen Sie in Ihrem Terminal den folgenden Befehl aus, um den privaten Schlüssel aus der .pfx-Datei zu extrahieren. Wenn Sie aufgefordert werden, eine Passphrase einzugeben, drücken Sie einfach die EINGABETASTE, wenn Sie keine festlegen möchten. Geben Sie andernfalls eine Passphrase Ihrer Wahl ein:

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

    Die Datei ciam-client-app-cert.key wird in Ihrer Anwendung verwendet.

Hochladen des Zertifikats in Ihre Anwendungsregistrierung

Um Ihr Client-Anwendungszertifikat zu verwenden, müssen Sie die Anwendung, die Sie im Microsoft Entra Admin Center registriert haben, dem Zertifikat zuordnen:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Symbol für Einstellungen im Menü oben, um über das Menü Verzeichnisse + Abonnements zum externen Mandanten zu wechseln.

  3. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.

  4. Wählen Sie in der Liste der Anwendungsregistrierungen die Anwendung aus, die Sie dem Zertifikat zuordnen möchten, z. B. ciam-client-app.

  5. Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.

  6. Wählen Sie Zertifikate und dann Zertifikat hochladen aus.

  7. Klicken Sie auf das Symbol Datei auswählen, und wählen Sie dann das Zertifikat aus, das Sie hochladen möchten, z. B. ciam-client-app-cert.pem oder ciam-client-app-cert.cer oder ciam-client-app-cert.crt.

  8. Geben Sie unter Beschreibung eine Beschreibung ein, z. B. CIAM-Client-Anwendungszertifikat, und wählen Sie dann Hinzufügen aus, um Ihr Zertifikat hochzuladen. Nachdem das Zertifikat hochgeladen wurde, werden der Fingerabdruck, das Startdatum und der Ablaufzeitpunkt angezeigt.

  9. Notieren Sie sich den Wert des Fingerabdrucks zur späteren Verwendung, wenn Sie Ihre Clientanwendung konfigurieren.

Wenn Sie bereits über einen geheimen Clientschlüssel für Ihre Anwendung verfügen, müssen Sie ihn löschen, um zu verhindern, dass sich eine bösartige Anwendung als Ihre Anwendung ausgibt:

  1. Wechseln Sie zur Registerkarte Clientgeheimnisse und wählen Sie das Symbol Löschen aus.
  2. Wählen Sie im angezeigten Popupfenster Ja aus.

Konfigurieren Ihrer Node.js-Anwendung für die Verwendung des Zertifikats

Nachdem Sie Ihre Anwendungsregistrierung mit dem Zertifikat verknüpft haben, müssen Sie Ihren Anwendungscode aktualisieren, um mit der Verwendung des Zertifikats zu beginnen:

  1. Suchen Sie die Datei, die Ihr MSAL-Konfigurationsobjekt enthält, z. B. msalConfig in authConfig.js, und aktualisieren Sie sie dann so, dass sie ähnlich dem folgenden Code aussieht. Wenn Sie über einen geheimen Clientschlüssel verfügen, müssen Sie ihn entfernen:

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

    Ersetzen Sie im Code die Platzhalter:

    • Add_Passphrase_Here mit der Passphrase, die Sie zum Verschlüsseln Ihres privaten Schlüssels verwendet haben.

    • YOUR_CERT_THUMBPRINT mit dem Wert des Fingerabdrucks, den Sie zuvor notiert haben.

    • PATH_TO_YOUR_PRIVATE_KEY_FILE mit dem Pfad zu Ihrer Datei mit dem privaten Schlüssel.

    • Enter_the_Application_Id_Here mit der Anwendungs-(Client)-ID der zuvor von Ihnen registrierten Anwendung.

    • Enter_the_Tenant_Subdomain_Here (Geben Sie hier die Unterdomäne Ihres Mandanten ein) und ersetzen Sie sie durch die Unterdomäne des Verzeichnisses (des Mandanten). Wenn Ihre primäre Mandantendomäne beispielsweise contoso.onmicrosoft.com lautet, verwenden Sie contoso. Wenn Sie ihren Mandantennamen nicht kennen, erfahren Sie, wie Sie Ihre Mandantendetails auslesen.

    Wir haben den Schlüssel verschlüsselt (wir empfehlen, dies zu tun), sodass wir ihn entschlüsseln müssen, bevor wir ihn an das MSAL-Konfigurationsobjekt übergeben.

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

const privateKey = privateKeyObject.export({
    format: 'pem',
    type: 'pkcs8'
});
//...

  2. Führen Sie die Schritte unter Ausführen und Testen der Webanwendung aus, um Ihre Anwendung zu testen.

Verwenden eines selbstsignierten Zertifikats direkt aus Azure Key Vault

Sie können ein vorhandenes Zertifikat direkt aus Azure Key Vault verwenden:

  1. Suchen Sie die Datei, die Ihr MSAL-Konfigurationsobjekt enthält, z. B. msalConfig in authConfig.js, und entfernen Sie dann die Eigenschaft 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. Installieren Sie die Azure CLI, und geben Sie dann auf Ihrer Konsole den folgenden Befehl ein, um sich anzumelden:

    az login --tenant YOUR_TENANT_ID

    Ersetzen Sie den Platzhalter YOUR_TENANT_ID durch die Verzeichnis-(Mandanten)-ID, die Sie zuvor kopiert haben.

  3. Geben Sie in Ihrer Konsole den folgenden Befehl ein, um die erforderlichen Pakete zu installieren:

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

  4. Verwenden Sie in Ihrer Clientanwendung den folgenden Code, um thumbprint und privateKey zu generieren:

    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();

    Ersetzen Sie im Code die Platzhalter:

    • ENTER_YOUR_KEY_VAULT_URL mit Ihrer Azure Key Vault-URL.

    • ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT mit dem Namen Ihres Zertifikats in Azure Key Vault.

  5. Verwenden Sie die Werte thumbprint und privateKey, um Ihre Konfiguration zu aktualisieren:

    let clientCert = {
    thumbprint: thumbprint, 
    privateKey: privateKey,
};

msalConfig.auth.clientCertificate = clientCert; //For this to work, you can't declares your msalConfig using const modifier

  6. Fahren Sie dann mit dem Instanziieren Ihres vertraulichen Clients fort, wie in der Methode getMsalInstance gezeigt:

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

  7. Führen Sie die Schritte unter Ausführen und Testen der Webanwendung aus, um Ihre Anwendung zu testen.

Nächste Schritte

In diesem Artikel werden folgende Themen erläutert: