Microsoft-verificatie-extensies voor Node

De Microsoft Authentication Extensions for Node biedt veilige mechanismen voor clienttoepassingen voor het uitvoeren van serialisatie en persistentie van tokens voor meerdere platforms.

MSAL Node vereist dat ontwikkelaars hun eigen logica implementeren voor het persistent maken van de tokencache. De MSAL Node-extensies zijn gericht op een robuuste, veilige en configureerbare implementatie van tokencaches in Windows, Mac en Linux voor openbare clienttoepassingen (desktopclients, CLI-toepassingen, enzovoort). Het biedt mechanismen voor het versleutelen en openen van de tokencache door meerdere processen tegelijk.

Ondersteunde platforms zijn Windows, Mac en Linux:

Windows - DPAPI wordt gebruikt voor versleuteling.
MAC - De MAC-sleutelhanger wordt gebruikt via npm keytar.
Linux - LibSecret wordt gebruikt voor het opslaan in 'Secret Service' via npm keytar.

Code

De persistentielaag maken

DE API voor het maken van de persistentielaag verschilt op basis van het platform waarop u zich richt.

U kunt ook de createPersistence API van PersistenceCreator gebruiken omdat het een algemene wrapper is en de juiste persistentiemethode selecteert op basis van het platform/besturingssysteem.

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

U kunt ook de onderstaande platformspecifieke opties gebruiken:


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 is het pad in het bestandssysteem waarin het versleutelde cachebestand wordt opgeslagen.
dataProtectionScope geeft het bereik van de gegevensbeveiliging, ofwel de huidige gebruiker of de lokale computer. U hebt geen sleutel nodig om de gegevens te beveiligen of de beveiliging op te heffen. Als u het bereik instelt op CurrentUser, kunnen alleen toepassingen die op uw referenties worden uitgevoerd, de beveiliging van de gegevens opheffen; Dit betekent echter dat elke toepassing die op uw referenties wordt uitgevoerd, toegang heeft tot de beveiligde gegevens. Als u het bereik instelt op LocalMachine, kan elke volledig vertrouwde toepassing op de computer de beveiliging van de gegevens opheffen, er toegang toe krijgen en deze wijzigen.
optionalEntropy geeft het wachtwoord of andere extra entropie op die wordt gebruikt om de gegevens te versleutelen.

Hierbij FilePersistenceWithDataProtection worden de Win32 CryptProtectData- en CryptUnprotectData-API's gebruikt. Raadpleeg de documentatie voor deze API's voor meer informatie over dataProtectionScope of optionalEntropy.

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

De cachePath locatie is niet waar de cache wordt opgeslagen. In plaats daarvan werken de extensies dit bestand bij met dummygegevens om de updatetijd van het bestand bij te werken, om te controleren of de inhoud van de sleutelhanger moet worden geladen of niet. Het wordt ook gebruikt als de locatie voor het vergrendelingsbestand. De servicenaam waaronder de cache wordt opgeslagen in de sleutelhanger. De accountnaam waaronder de cache is opgeslagen in de sleutelhanger.

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 is niet de locatie waar de cache wordt opgeslagen. In plaats daarvan passen de extensies dit bestand aan met dummygegevens om het wijzigingstijdstip van het bestand bij te werken, zodat kan worden gecontroleerd of de inhoud uit de secret service (bijvoorbeeld Gnome Keyring) moet worden geladen of niet. Het wordt ook gebruikt als de locatie voor het vergrendelingsbestand.

servicenaam waaronder de cache is opgeslagen de geheime service.
accountnaam waaronder de cache is opgeslagen in de geheime service.

Alle platforms

Een niet-versleutelde bestandspersistentie, die op alle platforms werkt, wordt voor het gemak aangeboden, hoewel dit niet wordt aanbevolen.

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

Als het bestand of de map nog niet bestaat, zal FilePersistence.create() het bestand en alle mappen in het pad recursief aanmaken. Dit kan in actie worden gezien in FilePersistence.ts

Vergrendelingsopties doorgeven aan de Cache-invoegtoepassing voor gelijktijdigheid

Maak de PersistenceCachePlugin, door het persistentieobject door te geven dat in de vorige stap is gemaakt.

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

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

De extensies gebruiken een vergrendeling op basis van bestanden om gelijktijdige toegang door meerdere processen te ondersteunen. U kunt via CrossPlatformLockOptions het aantal nieuwe pogingen en de vertraging voor het verkrijgen van een vergrendeling configureren.

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

De PersistenceCachePlugin instellen op de MSAL Node-configuratie `PublicClientApplication` (met een voorbeeld)

Samenvattend: zodra u een PersistenceCachePluginhebt, kunt u deze instellen voor de MSAL Node PublicClientApplicationdoor deze op te nemen in het object configuration, zoals hieronder wordt weergegeven.

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

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

const pca = new PublicClientApplication(publicClientConfig);

Voorbeeld (voor 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
};

Opmerking voor Electron-ontwikkelaars

Electron sample : In dit voorbeeld ziet u hoe u de bibliotheek msal-node-extensions integreert met uw elektronentoepassing die is gebundeld door webpack.

Als u deze extensie voor Electron gebruikt, kunt u een fout tegenkomen die er ongeveer als volgt uit ziet:

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

Deze fout is waarschijnlijk te wijten aan Node.js versieverschillen tussen het Electron-project en de extensie. Dit kan worden afgehandeld door het pakket opnieuw te bouwen met de volgende stappen:

Installeer electron-rebuild met de opdracht npm i -D electron-rebuild als u deze nog niet hebt geïnstalleerd.
Verwijderen packages-lock.json uit uw project als het bestaat
Voer ./node_modules/.bin/electron-rebuild uit

Samples

Feedback

Is deze pagina nuttig?

Last updated on 2026-07-02