Rozšíření ověřování Microsoftu pro Node

Rozšíření Microsoft Authentication pro Node nabízejí zabezpečené mechanismy, které klientským aplikacím umožňují provádět serializaci mezipaměti tokenů a její trvalé ukládání napříč platformami.

Uzel MSAL vyžaduje, aby vývojáři implementovali vlastní logiku pro zachování mezipaměti tokenů. Rozšíření MSAL Node cílí na robustní, zabezpečenou a konfigurovatelnou implementaci odolnosti mezipaměti tokenů napříč Windows, Mac a Linuxem pro veřejné klientské aplikace (desktopoví klienti, aplikace rozhraní příkazového řádku atd.). Poskytuje mechanismy pro šifrování a přístup k mezipaměti tokenů několika procesy současně.

Podporované platformy jsou Windows, Mac a Linux:

• Windows – ROZHRANÍ DPAPI se používá k šifrování.
• MAC – KeyChain MAC se používá prostřednictvím nástroje npm keytar.
• Linux – LibSecret se používá k ukládání do tajné služby prostřednictvím nástroje npm keytar.

Code

Vytvoření vrstvy trvalosti

Rozhraní API pro vytvoření vrstvy trvalosti se bude lišit podle toho, na jakou platformu cílíte.

Alternativně můžete použít createPersistence rozhraní API z PersistenceCreatoru , protože se jedná o obecnou obálku a vybere příslušnou metodu trvalosti na základě platformy nebo operačního systému.

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

Alternativně můžete použít následující možnosti specifické pro platformu:

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

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

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

Všechny platformy

Pro usnadnění práce se poskytuje nešifrovaná trvalost souborů, která funguje na všech platformách, i když se nedoporučuje.

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

Pokud nebyl vytvořen soubor nebo adresář, FilePersistence.create() vytvoří se soubor a všechny adresáře v cestě rekurzivně. To je vidět v akci v FilePersistence.ts

Předávání voleb zámku modulu Cache pro zajištění souběžnosti

Vytvořte objekt PersistenceCachePlugin, předáním objektu trvalosti, který byl vytvořen v předchozím kroku.

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

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

Pro podporu souběžného přístupu více procesů používají rozšíření zámek založený na souborech. Můžete nakonfigurovat číslo opakování a zpoždění opakování pro získání zámku prostřednictvím 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
        },
    });

Nastavení persistenceCachePlugin v konfiguraci uzlu PublicClientApplication MSAL (s příkladem)

Stručně řečeno, jakmile budete mít PersistenceCachePlugin, můžete jej nastavit v MSAL Node PublicClientApplication tak, že jej zahrnete do objektu configuration, jak je uvedeno níže.

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

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

const pca = new PublicClientApplication(publicClientConfig);

Příklad (pro desktopovou aplikaci Electron node-js):-

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

Poznámka pro elektronové vývojáře

Ukázka pro Electron: Tato ukázka znázorňuje, jak integrovat knihovnu msal-node-extensions do aplikace Electron, která byla sestavena pomocí Webpacku.

Pokud používáte toto rozšíření pro Elektron, může dojít k chybě podobné této:

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

Tato chyba je pravděpodobně způsobena rozdíly ve verzi Node.js mezi projektem Electron a rozšířením. Tento postup je možné zpracovat opětovným sestavením balíčku pomocí následujících kroků:

• Pokud ho ještě nemáte nainstalovaný, nainstalujte electron-rebuild ho pomocí příkazu npm i -D electron-rebuild .
• Odeberte packages-lock.json z vašeho projektu, pokud existuje
• Spusťte příkaz ./node_modules/.bin/electron-rebuild.

Ukázky

1. Ukázka Electron-webpack pro perzistenci
2. Ukázka rozšíření msal-node