Microsoft autentiseringstillägg för Node

Microsoft-autentiseringstillägg för Node erbjuder säkra mekanismer för klientprogram för att utföra cache-serialisering och beständighet mellan plattformar.

MSAL Node kräver att utvecklare implementerar sin egen logik för att bevara tokencachen. MSAL Node-tilläggen syftar till att tillhandahålla en robust, säker och konfigurerbar peristence-implementering av tokencache i Windows, Mac och Linux för offentliga klientprogram (skrivbordsklienter, CLI-program osv.). Den innehåller mekanismer för kryptering och åtkomst till tokencacheminnet av flera processer samtidigt.

Plattformar som stöds är Windows, Mac och Linux:

Windows – DPAPI används för kryptering.
MAC – MAC-nyckelringen används via npm-nyckeltar.
Linux – LibSecret används för lagring till "Secret Service" via npm-nyckeltar.

Code

Skapa beständighetsskiktet

API:et för att skapa beständighetsskiktet skiljer sig beroende på vilken plattform du riktar in dig på.

Du kan också använda API:et createPersistence från PersistenceCreator eftersom det är en allmän omslutning och väljer lämplig beständighetsmetod baserat på plattformen/operativsystemet.

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

Du kan också använda plattformsspecifika alternativ nedan:


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 är sökvägen i filsystemet där den krypterade cachefilen lagras.
dataProtectionScope anger dataskyddets omfattning, antingen den aktuella användaren eller den lokala datorn. Du behöver ingen nyckel för att skydda eller ta bort skyddet av data. Om du anger omfånget till CurrentUser kan endast program som körs på dina autentiseringsuppgifter ta bort skyddet av data. Det innebär dock att alla program som körs på dina autentiseringsuppgifter kan komma åt skyddade data. Om du anger omfånget till LocalMachine kan alla program med fullständigt förtroende på datorn ta bort skyddet, komma åt och ändra data.
optionalEntropy anger lösenord eller annan ytterligare entropi som används för att kryptera data.

FilePersistenceWithDataProtection Använder API:erna Win32 CryptProtectData och CryptUnprotectData. Mer information om dataProtectionScope eller optionalEntropy finns i dokumentationen för dessa API:er.

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

Det cachePath är inte där cachen lagras. I stället uppdaterar tilläggen den här filen med dummydata för att uppdatera filens uppdateringstid för att kontrollera om innehållet i nyckelringen ska läsas in eller inte. Den används också som plats för låsfilen. Tjänstnamnet under vilket cachen lagras i nyckelringen. Det kontonamn under vilket cachen lagras i nyckelringen.

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

CachePath är inte där cachen kommer att lagras. I stället uppdaterar tilläggen den här filen med dummydata för att ändra filens ändringstid, för att avgöra om innehållet i Secret Service (till exempel Gnome Keyring) ska läsas in eller inte. Den används också som plats för låsfilen.

tjänstnamn under vilket cachen lagras i säkerhetstjänsten.
kontonamn under vilket cachen lagras i secret service.

Alla plattformar

En okrypterad filpersistence, som fungerar på alla plattformar, tillhandahålls för enkelhetens skull, men rekommenderas inte.

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

Om filen eller katalogen inte har skapats FilePersistence.create() skapar du filen och eventuella kataloger i sökvägen rekursivt. Detta kan ses i praktiken i FilePersistence.ts

Skicka låsalternativ till cache-plugin-programmet för samtidighet

Skapa PersistenceCachePlugin, genom att skicka in persistensobjektet som skapades i föregående steg.

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

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

För att stödja samtidig åtkomst med flera processer använder tilläggen ett filbaserat lås. Du kan konfigurera antal återförsök och fördröjningen mellan återförsök för låsinhämtning via CrossPlatformLockOptions.

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

Ange PersistenceCachePlugin i MSAL Node-konfigurationen `PublicClientApplication` (med ett exempel)

Sammanfattnings skull, när du har en PersistenceCachePlugin, som kan anges på MSAL-noden PublicClientApplicationgenom att ange den som en del av konfigurationsobjektet enligt nedan.

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

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

const pca = new PublicClientApplication(publicClientConfig);

Exempel (för Elektron node-js skrivbordsapp):-

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

Obs! För elektronutvecklare

Elektronexempel: Det här exemplet visar hur du integrerar msal-node-extensions-biblioteket i ditt elektronprogram som har paketerats av webpack.

Om du använder det här tillägget för Electron kan du stöta på ett fel som liknar detta:

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...."

Det här felet beror förmodligen på Node.js versionsskillnader mellan Electron-projektet och tillägget. Detta kan hanteras genom att du återskapar paketet med följande steg:

Installera electron-rebuild med kommandot npm i -D electron-rebuild om du inte redan har installerat det.
Ta bort packages-lock.json från projektet om det finns
Kör ./node_modules/.bin/electron-rebuild

Samples

Feedback

Var den här sidan till hjälp?

Last updated on 2026-07-02