Microsoft Csomópont hitelesítési bővítményei

A Microsoft Authentication Extensions for Node biztonságos mechanizmusokat kínál ahhoz, hogy az ügyfélalkalmazások platformfüggetlen módon végezhessék a tokengyorsítótár szerializálását és megőrzését.

Az MSAL Node megköveteli, hogy a fejlesztők saját logikát valósítsanak meg a tokengyorsítótár tartós tárolására. Az MSAL Node-bővítmények célja, hogy robusztus, biztonságos és konfigurálható megoldást biztosítsanak a jogkivonat-gyorsítótár perzisztenciájának megvalósítására Windows, Mac és Linux rendszereken a nyilvános ügyfélalkalmazások (asztali kliensek, parancssori alkalmazások stb.) számára. Mechanizmusokat biztosít a titkosításhoz, valamint a tokengyorsítótár eléréséhez egyszerre több folyamattal.

A támogatott platformok Windows, Mac és Linux:

Windows – A DPAPI titkosításra szolgál.
MAC – A MAC-kulcskarika az npm billentyűtáron keresztül használható.
Linux – A LibSecret a "Secret Service"-hez való tároláshoz használható az npm-kulcstáron keresztül.

Code

A perzisztenciaréteg létrehozása

A perzisztenciaréteg létrehozásához használt API a megcélzott platformtól függően eltérő lesz.

Másik lehetőségként használhatja a createPersistencePersistenceCreator API-t általános burkolóként, és a platform/operációs rendszer alapján kiválasztja a megfelelő adatmegőrzési módszert.

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

Másik lehetőségként az alábbi platformspecifikus lehetőségeket is használhatja:


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 a titkosított gyorsítótárfájl tárolására szolgáló fájlrendszer elérési útja.
dataProtectionScope az adatvédelem hatókörét határozza meg, akár az aktuális felhasználó, akár a helyi gép. Az adatok védelméhez vagy feloldásához nincs szükség kulcsra. Ha a hatókört CurrentUser értékre állítja, csak a hitelesítő adatokon futó alkalmazások oldhatják fel az adatok védelmét; Ez azonban azt jelenti, hogy a hitelesítő adatokon futó alkalmazások hozzáférhetnek a védett adatokhoz. Ha a hatókört LocalMachine értékre állítja, a számítógépen található összes teljes megbízhatósági alkalmazás feloldhatja az adatok védelmét, elérését és módosítását.
optionalEntropy az adatok titkosításához használt jelszót vagy egyéb további entrópiát adja meg.

A FilePersistenceWithDataProtection Win32 CryptProtectData és a CryptUnprotectData API-kat használja. A dataProtectionScope vagy az optionalEntropy szolgáltatással kapcsolatos további információkért tekintse meg az adott API-k dokumentációját.

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

A cachePath gyorsítótár nem itt lesz tárolva. Ehelyett a bővítmények áladatokkal frissítik ezt a fájlt, hogy módosítsák a fájl frissítési idejét, és ellenőrizzék, hogy be kell-e tölteni a kulcstartó tartalmát. A zárolási fájl helyeként is használatos. Az a szolgáltatásnév, amely alatt a gyorsítótár a kulcskarikában van tárolva. A fiók neve, amely alatt a gyorsítótár a kulcskarikában van tárolva.

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

A cachePath nem az a hely, ahol a gyorsítótár tárolódni fog. Ehelyett a bővítmények a fájl frissítési idejének frissítéséhez módosítják ezt a fájlt titkos adatokkal, és ellenőrzik, hogy a titkos szolgáltatás (például a Gnome Keyring) tartalma betöltődik-e vagy sem. A zárolási fájl helyeként is használatos.

szolgáltatásnév, amely alatt a gyorsítótárat a titkos szolgáltatás tárolja.
fióknév, amely alatt a gyorsítótár a titkos szolgáltatásban van tárolva.

Az összes platform

A titkosítás nélküli fájlmegőrzés, amely minden platformon működik, kényelmes, bár nem ajánlott.

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

Ha a fájl vagy könyvtár nem lett létrehozva, FilePersistence.create() rekurzív módon hozza létre a fájlt és az elérési úton lévő könyvtárakat. Ez működés közben látható a FilePersistence.ts

Zárolási beállítások átadása a Gyorsítótár bővítménynek konkurenciakezeléshez

Hozza létre a PersistenceCachePlugin elemet az előző lépésben létrehozott perzisztenciaobjektum átadásával.

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

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

Ha több folyamat egyidejű elérését szeretné támogatni, a bővítmények fájlalapú zárolást használnak. A CrossPlatformLockOptions segítségével konfigurálhatja a zárolás megszerzéséhez tartozó újrapróbálkozások számát és az újrapróbálkozás késleltetését.

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

A PersistenceCachePlugin beállítása az MSAL-csomópont `PublicClientApplication` konfigurációján (egy példával)

Összefoglalva: ha már rendelkezik egy PersistenceCachePlugin elemmel, azt az alább látható módon beállíthatja az MSAL Node PublicClientApplication elemben, a konfigurációs objektum részeként.

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

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

const pca = new PublicClientApplication(publicClientConfig);

Példa (az Electron node-js asztali alkalmazáshoz):-

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

Megjegyzés az Electron fejlesztőinek

Elektronminta: Ez a minta bemutatja, hogyan integrálható a msal-node-extensions kódtár a webpack által csomagolt elektronalkalmazásba.

Ha ezt a bővítményt használja az Electronhez, az alábbihoz hasonló hibaüzenet jelenhet meg:

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

Ez a hiba valószínűleg az Electron-projekt és a bővítmény közötti Node.js verzióeltérésnek köszönhető. Ez a csomag újraépítésével kezelhető az alábbi lépésekkel:

Telepítse a(z) electron-rebuild-t a(z) npm i -D electron-rebuild paranccsal, ha még nincs telepítve.
Távolítsa el a(z) packages-lock.json elemet a projektből, ha van
Az ./node_modules/.bin/electron-rebuild parancs futtatása

Samples

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-07-02