Verwenden von Zertifikatsanmeldeinformationen mit MSAL Node

Sie können vertrauliche Clientanwendungen mit MSAL Node (Web-Apps, Daemon-Apps usw.) erstellen. Für vertrauliche Clients ist eine Anmeldeinformation erforderlich.

Voraussetzungen

• Ein gutes Verständnis für die Initialisierung vertraulicher Clientanwendungen.

Sie können vertrauliche Clientanwendungen mit MSAL Node (Web-Apps, Daemon-Apps usw.) erstellen. Für vertrauliche Clients ist eine Clientanmeldeinformation erforderlich. Clientanmeldeinformationen können folgendes sein:

• managed identity: Dies ist ein zertifikatloses Szenario, in dem die Vertrauensstellung über die Azure-Infrastruktur hergestellt wird. Es ist kein geheimer Schlüssel/Zertifikatverwaltung erforderlich. MSAL implementiert dieses Feature noch nicht, sie können aber stattdessen Azure Identity SDK verwenden. Siehe Dokumentation zu verwalteten Identitäten für Azure Ressourcen
• clientSecret: eine geheime Zeichenfolge, die während der App-Registrierung generiert oder nach der Registrierung für eine vorhandene Anwendung aktualisiert wurde. Dies wird nicht für die Produktion empfohlen.
• clientCertificate: ein Zertifikat, das während der App-Registrierung festgelegt wurde. Das Zertifikat muss über den privaten Schlüssel verfügen, da es zum Signieren einer Assertion verwendet wird, die MSAL generiert. Das thumbprintSha256 ist ein X.509-SHA-256-Fingerabdruck des Zertifikats, und das privateKey ist der PEM-kodierte private Schlüssel.
• clientAssertion: Anstatt MSAL eine Assertion erstellen zu lassen, übernimmt der App-Entwickler die Steuerung. Nützlich zum Hinzufügen zusätzlicher Ansprüche zur Assertion oder zum Verwenden von KeyVault zum Signieren anstelle eines lokalen Zertifikats. Das Zertifikat, das zum Signieren der Assertion verwendet wird, muss während der App-Registrierung noch festgelegt werden.

Hinweis: 1p-Apps müssen möglicherweise auch x5c senden. Dies ist die X.509-Zertifikatskette, die in Authentifizierungsszenarien mit Subjektnamen/Ausstellern verwendet wird.

Sicheres Verwenden von geheimen Schlüsseln und Zertifikaten

Geheime Schlüssel sollten niemals hartcodiert werden. Das dotenv npm-Paket kann verwendet werden, um geheime Schlüssel oder Zertifikate in einer env-Datei (im Stammverzeichnis des Projekts) zu speichern, die in gitignore enthalten sein sollte, um versehentliche Uploads der geheimen Schlüssel zu verhindern.

Zertifikate können auch über das fs-Modul von NodeJS aus Dateien eingelesen werden. Sie sollten jedoch niemals im Verzeichnis des Projekts gespeichert werden. Produktions-Apps sollten Zertifikate von Azure KeyVault oder anderen sicheren Schlüsseltresorn abrufen.

Weitere Informationen finden Sie unter Zertifikaten und geheimen Schlüsseln .

Siehe MSAL-Beispiel: Authentifizierungscode mit Zertifikaten

Registrieren von Zertifikaten

Wenn Sie kein Zertifikat besitzen, können Sie ein selbstsigniertes Zertifikat mithilfe von PowerShell oder mit Azure KeyVault erstellen.

Sie müssen Ihr Zertifikat auf Microsoft Entra ID hochladen.

1. Navigieren Sie zu Azure Portal, und wählen Sie Ihre Microsoft Entra App-Registrierung aus.
2. Wählen Sie das Blatt "Zertifikate und Geheime Schlüssel " auf der linken Seite aus.
3. Klicken Sie auf "Zertifikat hochladen ", und wählen Sie die hochzuladende Zertifikatdatei aus (z. B. beispiel.crt).
4. Klicken Sie auf Hinzufügen. Nachdem das Zertifikat hochgeladen wurde, werden der Fingerabdruck (SHA-256),das Startdatum und die Ablaufwerte angezeigt.

Weitere Informationen finden Sie unter: Registrieren Ihres Zertifikats mit Microsoft Identity Platform

Initialisieren von MSAL-Knoten mit Zertifikaten

const msal = require('@azure/msal-node');
require('dotenv').config(); // process.env now has the values defined in a .env file

const config = {
    auth: {
        clientId: "YOUR_CLIENT_ID",
        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
        clientCertificate: {
            thumbprintSha256: process.env.thumbprint,
            privateKey: process.env.privateKey,
        }
    }
};

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

Beide thumbprintSha256 und privateKey werden als Zeichenfolgen erwartet. privateKey wird außerdem in der folgenden Form erwartet (PKCS#8):

-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQDkpKPrsfpIijS3
z2HCpDsa7dxOsKIrm7F1AtGBjyB0yVDjlh/FA7jT5sd2ypBh3FVsZGJudQsLRKfE
// ...
-----END ENCRYPTED PRIVATE KEY-----

openssl pkcs8 -topk8 -inform PEM -outform PEM -in example.key -out example.key

Wenn Sie Ihren privaten Schlüssel (oder wenn Ihr privater Schlüssel bereits mit einem Passbegriff verschlüsselt ist) verschlüsselt haben, müssen Sie ihn entschlüsseln, bevor Sie ihn an MSAL Node übergeben.

Wichtig: Niemals Hartcodieren von Kennwörtern im Quellcode. Sowohl der private Zertifikatschlüssel als auch das optionale Verschlüsselungskennwort sollten von einem sicheren Speicherort (z. B. Azure KeyVault) abgerufen und sicher mit Ihrer Web-API bereitgestellt werden.

Dies kann mithilfe des Kryptomoduls von Node erfolgen. Verwenden Sie die createPrivateKey() Methode, um Ihren Schlüssel zu analysieren und zu exportieren:

const fs = require('fs');
const crypto = require('crypto');

const privateKeySource = fs.readFileSync('<path_to_key>/example.key')

const privateKeyObject = crypto.createPrivateKey({
    key: privateKeySource,
    passphrase: process.env.YOUR_PASSPHRASE,
    format: 'pem'
});

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

(Optional) Konvertieren von pfx in pem

OpenSSL kann zum Konvertieren von pfx-codierten Zertifikatdateien in pem verwendet werden:

    openssl pkcs12 -in certificate.pfx -out certificate.pem

Wenn die Konvertierung programmgesteuert erfolgen muss, müssen Sie sich möglicherweise auf ein Drittanbieterpaket verlassen, da Node.js hierfür keine systemeigene Methode bietet. Beispielsweise können Sie mithilfe einer beliebten TLS-Implementierung wie node-forge folgende Aktionen ausführen:

const forge = require('node-forge');

/**
 * @param {string} pfx: certificate + private key combination in pfx format
 * @param {string} passphrase: passphrase used to encrypt pfx file
 * @returns {Object}
 */
function convertPFX(pfx, passphrase = null) {

    const asn = forge.asn1.fromDer(forge.util.decode64(pfx));
    const p12 = forge.pkcs12.pkcs12FromAsn1(asn, true, passphrase);

    // Retrieve key data
    const keyData = p12.getBags({ bagType: forge.pki.oids.pkcs8ShroudedKeyBag })[forge.pki.oids.pkcs8ShroudedKeyBag]
        .concat(p12.getBags({ bagType: forge.pki.oids.keyBag })[forge.pki.oids.keyBag]);

    // Retrieve certificate data
    const certBags = p12.getBags({ bagType: forge.pki.oids.certBag })[forge.pki.oids.certBag];
    const certificate = forge.pki.certificateToPem(certBags[0].cert)

    // Convert a Forge private key to an ASN.1 RSAPrivateKey
    const rsaPrivateKey = forge.pki.privateKeyToAsn1(keyData[0].key);

    // Wrap an RSAPrivateKey ASN.1 object in a PKCS#8 ASN.1 PrivateKeyInfo
    const privateKeyInfo = forge.pki.wrapRsaPrivateKey(rsaPrivateKey);

    // Convert a PKCS#8 ASN.1 PrivateKeyInfo to PEM
    const privateKey = forge.pki.privateKeyInfoToPem(privateKeyInfo);

    console.log("Converted certificate: \n", certificate);
    console.log("Converted key: \n", privateKey);

    return {
        certificate: certificate,
        key: privateKey
    };
}

(Optional) Erstellen eines HTTPS-Servers

Das OAuth 2.0-Protokoll empfiehlt, wann immer möglich eine HTTPS-Verbindung zu verwenden. Die meisten Clouddienste wie Azure App Service stellen standardmäßig https-Verbindung über proxy bereit. Wenn Sie zu Testzwecken Ihren eigenen HTTPS-Server einrichten möchten, finden Sie in der dokumentation zu Node.js Anleitungen zum Erstellen eines HTTPS-Servers.

Außerdem müssen Sie Ihre selbstsignierten Zertifikate zurSchlüsselkette des / Ihres Betriebssystems hinzufügen, um die Sicherheitsrichtlinie des Browsers zu umgehen. Möglicherweise wird in Ihrem Browser nach wie vor eine Warnung angezeigt (z. B. Chrome).

• Für Windows Benutzer folgen Sie der Anleitung hier: Vorgehensweise: Anzeigen von Zertifikaten mit dem MMC-Snap-In.

• Für Linux- und MacOS-Benutzer lesen Sie bitte Ihre Betriebssystemdokumentation zum Installieren von Zertifikaten.

Häufig auftretende Probleme

In einigen Fällen erhalten Sie möglicherweise eine Fehlermeldung von Microsoft Entra ID, wenn Sie versuchen, Zertifikate zu authentifizieren, z. B. den AADSTS700027: Client assertion contains an invalid signature Fehler, der angibt, dass die Zertifikate und/oder privaten Schlüssel, die Sie zum Initialisieren von MSAL-Knoten verwenden, falsch formatiert sind. Ein häufiger Grund hierfür ist, dass die Zertifikat-/private Schlüsselzeichenfolge, die Sie MSAL Node bereitstellen, unerwartete Zeichen enthält, beispielsweise Wagenrücklauf (\r) oder Zeilenvorschübe (\n):

-----BEGIN CERTIFICATE-----\nMIIDDzCCAfegAwIBAgIJAMkyzQVK88NHMA0GCSqGSIb3DQEBBQUAMIGCMQswCQYDVQQGEwJTRTESMBAGA1UECBMJU3RvY2tob2xtMQ4wDAYDVQQHEwVLaXN0YTEQMA4G0fbkqbKulrchGbNgkankZtEVg4PGjobZq7B+njvcVa7SsWF/WLq5AUbw==\r\n-----END CERTIFICATE-----

Alternativ kann Ihre Zertifikats- bzw. Schlüsseldatei Bag-Attribute enthalten:

Bag Attributes
    localKeyID: 28 B5 8E 16 11 88 E9 00 58 D5 76 30 12 B9 59 B8 E4 CE 7C AA
subject=/C=UK/ST=Suffolk/L=Ipswich/O=Example plc/CN=alice
issuer=/C=UK/ST=Suffolk/L=Ipswich/O=Example plc/CN=Certificate Authority/emailAddress=ca@example.com\n
-----BEGIN CERTIFICATE-----
MIIDDzCCAfegAwIBAgIJAMkyzQVK88NHMA0GCSqGSIb3DQEBBQUAMIGCMQswCQYD
VQQGEwJTRTESMBAGA1UECBMJU3RvY2tob2xtMQ4wDAYDVQQHEwVLaXN0YTEQMA4G
0fbkqbKulrchGbNgkankZtEVg4PGjo+Y8MdMjtfSZB29hwYvfMX09jzJ68ZqmpYQ
njvcVtLbEZN5OGCkaslb/f2OxLbsUNgIbws538WnaaufDvKmQe2kUdWmpl9Wn9Bf
bZq7B+njvcVa7SsWF/WLq5AUbw==
-----END CERTIFICATE-----

In solchen Fällen sind Sie dafür verantwortlich, die Zeichenfolge zu bereinigen, bevor Sie sie an die MSAL Node-Konfiguration übergeben. Beispiel:

const msal = require('@azure/msal-node');
const fs = require('fs');

const privateKeySource = fs.readFileSync('<path_to_key>/certs/example.key');
const privateKey = Buffer.from(privateKeySource, 'base64').toString().replace(/\r/g, "").replace(/\n/g, "");

const config = {
    auth: {
        clientId: "YOUR_CLIENT_ID",
        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
        clientCertificate: {
            thumbprintSha256: process.env.thumbprint,
            privateKey: privateKey,
        }
    }
};

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

Siehe auch

• Anmeldeinformationen für die Microsoft Identity Platform-Anwendungsauthentifizierung
• Erstellen eines selbstsignierten öffentlichen Zertifikats zur Authentifizierung Ihrer Anwendung
• Verschiedene SSL/TLS-Zertifikatdateitypen/Erweiterungen