Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Microsoft Authentication Extensions for Node enables developers to perform cross-platform token cache serialization and persistence to disk. It gives extra support to the Microsoft Authentication Library (MSAL) for Node.
The MSAL for Node supports an in-memory cache by default and provides the ICachePlugin interface to perform cache serialization, but doesn't provide a default way of storing the token cache to disk. The Microsoft Authentication Extensions for Node is the default implementation for persisting cache to disk across different platforms.
The Microsoft Authentication Extensions for Node support the following platforms:
- Windows - Data protection API (DPAPI) is used for protection.
- Mac - The Mac Keychain is used.
- Linux - LibSecret is used for storing to "Secret Service".
The msal-node-extensions
package is available on Node Package Manager (NPM).
npm i @azure/msal-node-extensions --save
Here's an example of code that uses Microsoft Authentication Extensions for Node to configure the token cache.
const {
DataProtectionScope,
Environment,
PersistenceCreator,
PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");
// You can use the helper functions provided through the Environment class to construct your cache path
// The helper functions provide consistent implementations across Windows, Mac and Linux.
const cachePath = path.join(Environment.getUserRootDirectory(), "./cache.json");
const persistenceConfiguration = {
cachePath,
dataProtectionScope: DataProtectionScope.CurrentUser,
serviceName: "<SERVICE-NAME>",
accountName: "<ACCOUNT-NAME>",
usePlaintextFileOnLinux: false,
};
// The PersistenceCreator obfuscates a lot of the complexity by doing the following actions for you :-
// 1. Detects the environment the application is running on and initializes the right persistence instance for the environment.
// 2. Performs persistence validation for you.
// 3. Performs any fallbacks if necessary.
PersistenceCreator.createPersistence(persistenceConfiguration).then(
async (persistence) => {
const publicClientConfig = {
auth: {
clientId: "<CLIENT-ID>",
authority: "<AUTHORITY>",
},
// This hooks up the cross-platform cache into MSAL
cache: {
cachePlugin: new PersistenceCachePlugin(persistence),
},
};
const pca = new msal.PublicClientApplication(publicClientConfig);
// Use the public client application as required...
}
);
The following table provides an explanation for all the arguments for the persistence configuration.
Field Name | Description | Required For |
---|---|---|
cachePath | The path to the lock file the library uses to synchronize the reads and the writes | Windows, Mac, and Linux |
dataProtectionScope | Specifies the scope of the data protection on Windows either the current user or the local machine. | Windows |
serviceName | Specifies the service name to be used on Mac and/or Linux | Mac and Linux |
accountName | Specifies the account name to be used on Mac and/or Linux | Mac and Linux |
usePlaintextFileOnLinux | The flag to default to plain text on linux if LibSecret fails. Defaults to false |
Linux |
For more information about Microsoft Authentication Extensions for Node and MSAL Node, see: