Microsoft-Authentifizierungserweiterungen für Node

Die Microsoft-Authentifizierungserweiterungen für Node bieten sichere Mechanismen, um Clientanwendungen die plattformübergreifende Tokencacheserialisierung und -persistenz zu ermöglichen.

MSAL Node erfordert, dass Entwickler ihre eigene Logik zum Speichern des Tokencaches implementieren. Die MSAL Node-Erweiterungen zielen darauf ab, eine robuste, sichere und konfigurierbare Tokencache-Implementierung in Windows, Mac und Linux für öffentliche Clientanwendungen (Desktopclients, CLI-Anwendungen usw.) bereitzustellen. Es stellt Mechanismen zum Verschlüsseln und Zugreifen auf den Tokencache durch mehrere Prozesse gleichzeitig bereit.

Unterstützte Plattformen sind Windows, Mac und Linux:

Windows – DPAPI wird für die Verschlüsselung verwendet.
MAC – Der MAC-Schlüsselbund wird über npm keytar verwendet.
Linux - LibSecret wird zum Speichern in "Secret Service" über npm keytar verwendet.

Code

Erstellen der Persistenzebene

Die API zum Erstellen der Persistenzschicht unterscheidet sich je nach Plattform, auf die Sie abzielen.

Alternativ können Sie die createPersistence API von PersistenceCreator als generischen Wrapper verwenden und die entsprechende Persistenzmethode basierend auf der Plattform/dem Betriebssystem auswählen.

const { PublicClientApplication } = require("@azure/msal-node");
const {
  DataProtectionScope,
  PersistenceCreator,
  PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

const persistence = await PersistenceCreator.createPersistence({
                cachePath: "path/to/cache/file.json",
                dataProtectionScope: DataProtectionScope.CurrentUser,
                serviceName: "test-msal-electron-service",
                accountName: "test-msal-electron-account",
                usePlaintextFileOnLinux: false,
          });
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(persistence);
                    },
                });

Alternativ können Sie die folgenden plattformspezifischen Optionen verwenden:


const { FilePersistenceWithDataProtection, DataProtectionScope } = require("@azure/msal-node-extensions");
const { PublicClientApplication } = require("@azure/msal-node");

const cachePath = "path/to/cache/file.json";
const dataProtectionScope = DataProtectionScope.CurrentUser;
const optionalEntropy = ""; //specifies password or other additional entropy used to encrypt the data.
const windowsPersistence = await FilePersistenceWithDataProtection.create(cachePath, dataProtectionScope, optionalEntropy);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(windowsPersistence);
                    },
                });

cachePath ist der Pfad im Dateisystem, in dem die verschlüsselte Cachedatei gespeichert wird.
dataProtectionScope gibt den Umfang des Datenschutzes an, entweder der aktuelle Benutzer oder der lokale Computer. Sie benötigen keinen Schlüssel, um die Daten zu schützen oder aufzuheben. Wenn Sie den Bereich auf CurrentUser festlegen, können nur Anwendungen, die auf Ihren Anmeldeinformationen ausgeführt werden, den Schutz der Daten aufheben. Das bedeutet jedoch, dass jede Anwendung, die auf Ihren Anmeldeinformationen ausgeführt wird, auf die geschützten Daten zugreifen kann. Wenn Sie den Bereich auf LocalMachine festlegen, kann jede voll vertrauenswürdige Anwendung auf dem Computer den Schutz aufheben, darauf zugreifen und die Daten ändern.
optionalEntropy gibt ein Kennwort oder eine andere zusätzliche Entropie an, die zum Verschlüsseln der Daten verwendet wird.

Das FilePersistenceWithDataProtection verwendet die Win32-APIs CryptProtectData und CryptUnprotectData. Weitere Informationen zu dataProtectionScope oder optionalEntropy finden Sie in der Dokumentation dieser APIs.

const { KeychainPersistence } = require("@azure/msal-node-extensions");

const cachePath = "path/to/cache/file.json";
const serviceName = "test-msal-electron-service";
const accountName = "test-msal-electron-account";
const macPersistence = await KeychainPersistence.create(cachePath, serviceName, accountName);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(macPersistence);
                    },
                });

Der cachePath ist nicht der Ort, an dem der Cache gespeichert wird. Stattdessen aktualisieren die Erweiterungen diese Datei mit Dummy-Daten, um die Aktualisierungszeit der Datei zu aktualisieren, um zu überprüfen, ob der Inhalt des Schlüsselbunds geladen werden soll oder nicht. Sie wird auch als Speicherort für die Sperrdatei verwendet. Der Dienstname, unter dem der Cache im Schlüsselbund gespeichert wird. Der Kontoname, unter dem der Cache im Schlüsselbund gespeichert wird.

const { LibSecretPersistence } = require("@azure/msal-node-extensions");

const cachePath = "path/to/cache/file.json";
const serviceName = "test-msal-electron-service";
const accountName = "test-msal-electron-account";
const linuxPersistence = await LibSecretPersistence.create(cachePath, serviceName, accountName);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(linuxPersistence);
                    },
                });

Der cachePath ist nicht der Ort, an dem der Cache gespeichert wird. Stattdessen aktualisieren die Erweiterungen diese Datei mit Dummy-Daten, um den Zeitstempel der Datei zu aktualisieren, um zu prüfen, ob die Inhalte aus dem Secret Service (zum Beispiel Gnome Keyring) geladen werden sollen oder nicht. Sie wird auch als Speicherort für die Sperrdatei verwendet.

Dienstname, unter dem der Cache im Secret Service gespeichert wird.
Kontoname, unter dem der Cache im Geheimdienst gespeichert ist.

Alle Plattformen

Eine unverschlüsselte Dateipersistenz, die auf allen Plattformen funktioniert, wird zur Bequemlichkeit bereitgestellt, obwohl nicht empfohlen.

const { FilePersistence } = require("@azure/msal-node-extensions");

const filePath = "path/to/cache/file.json";
const filePersistence = await FilePersistence.create(filePath, loggerOptions);
// Pass the persistence to msal config's cachePlugin
const pca = new PublicClientApplication({
    auth: {
            clientId: "CLIENT_ID_HERE",
        },
    cache: {
            cachePlugin: new PersistenceCachePlugin(filePersistence);
        },
  });

Wenn keine Datei oder ein Verzeichnis erstellt wurde, FilePersistence.create() wird die Datei und alle Verzeichnisse im Pfad rekursiv erstellt. Dies kann in FilePersistence.ts in Aktion gesehen werden.

Übergeben von Sperroptionen an das Cache-Plug-In zwecks Parallelität

Erstellen Sie das PersistenceCachePlugin, indem Sie das Persistenzobjekt übergeben, das im vorherigen Schritt erstellt wurde.

const { PersistenceCachePlugin } = require("@azure/msal-node-extensions");

const persistenceCachePlugin = new PersistenceCachePlugin(windowsPersistence); // or any of the other ones.

Zur Unterstützung des gleichzeitigen Zugriffs durch mehrere Prozesse verwenden die Erweiterungen eine dateibasierte Sperre. Sie können die Anzahl der Wiederholungsversuche und die Wiederholungsverzögerung für den Erwerb der Sperre über CrossPlatformLockOptions konfigurieren.

const {
  PersistenceCreator,
  PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

const lockOptions = {
    retryNumber: 100,
    retryDelay: 50
}

const persistence = await PersistenceCreator.createPersistence(persistenceConfiguration);
const persistenceCachePlugin = new PersistenceCachePlugin(persistence, lockOptions); // or any of the other ones
const pca = new PublicClientApplication({
    auth: {
            clientId: "CLIENT_ID_HERE",
        },
    cache: {
            cachePlugin: persistenceCachePlugin
        },
    });

Festlegen des PersistenceCachePlugin für die MSAL-Knotenkonfiguration `PublicClientApplication` (mit einem Beispiel)

Zusammenfassend lässt sich sagen: Sobald Sie ein PersistenceCachePlugin haben, kann dieses für PublicClientApplication in MSAL Node festgelegt werden, indem es wie unten gezeigt als Teil des Konfigurationsobjekts festgelegt wird.

import { PublicClientApplication } from "@azure/msal-node";

const publicClientConfig = {
    auth: {
        clientId: "",
        authority: "",
    },
    cache: {
        cachePlugin: persistenceCachePlugin
    },
};

const pca = new PublicClientApplication(publicClientConfig);

Beispiel (für Electron node-js Desktop-App):-

authConfig.js:-

const AAD_ENDPOINT_HOST = "https://login.microsoftonline.com/"; // include the trailing slash
const REDIRECT_URI = "ENTER_REDIRECT_URI";

const cachePath = "path/to/cache/file.json";

/*define persistence config based on the appropriate persistence you are using(e.g- FilePersistenceWithDataProtection, generic PersistenceCreateor, etc)*/

//defining persistence config for PersistenceCreator
const persistenceConfiguration = {
    cachePath,
    dataProtectionScope: DataProtectionScope.CurrentUser,
    serviceName: "test-msal-electron-service",
    accountName: "test-msal-electron-account",
    usePlaintextFileOnLinux: false,
}

  const msalConfig = {
    auth: {
        clientId: "CLIENT_ID_HERE",
        authority: `${AAD_ENDPOINT_HOST}TENANT_ID_HERE`,
    },
    cache: {
        cachePlugin: null // set later in main.js as shown above 
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: LogLevel.Verbose,
        },
    },
};
...

module.exports = {
  msalConfig: msalConfig,
  protectedResources: protectedResources,
  REDIRECT_URI: REDIRECT_URI,
  persistenceConfiguration
};

Hinweis für Elektronenentwickler

Elektronenbeispiel: In diesem Beispiel wird gezeigt, wie sie die Msal-node-extensions-Bibliothek in Ihre Elektronenanwendung integrieren, die von webpack gebündelt wurde.

Wenn Sie diese Erweiterung für Electron verwenden, tritt möglicherweise ein Fehler auf, der dem folgenden ähnelt:

Uncaught Exception:
Error: The module
"<path-to-project>\node_modules\...\dpapi.node" was compiled against a different Node.js version using NODE_MODULE_VERSION 85. This version of Node.js requires NODE_MODULE_VERSION 80. Please try re-compiling or re-installing the module...."

Dieser Fehler ist wahrscheinlich auf Node.js Versionsunterschiede zwischen dem Electron-Projekt und der Erweiterung zurückzuführen. Dies kann durch erneutes Erstellen des Pakets mit den folgenden Schritten behandelt werden:

Installieren Sie electron-rebuild mit dem Befehl npm i -D electron-rebuild, falls es noch nicht installiert ist.
Entfernen packages-lock.json aus Ihrem Projekt, falls vorhanden
Führen Sie ./node_modules/.bin/electron-rebuild aus

Beispiele

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-02