Microsoft Authentication Library Extensions

1.3.1 verified Tue May 12 auth: no python install: verified quickstart: stale

MSAL EX provides a persistence API for saving data on disk, encrypted on Windows, macOS, and Linux, with concurrent data access coordinated by a file lock mechanism. Current version: 1.3.1, released on March 14, 2025. Release cadence: approximately quarterly.

pip install msal-extensions

Common errors

error ModuleNotFoundError: No module named 'distutils' ↓

cause This error occurs in Python 3.12 and later because the `distutils` package, which `msal-extensions` (or its dependency `azure-identity`) historically used for version parsing, was removed from the standard library in Python 3.12.

fix

Upgrade msal-extensions to a version that supports Python 3.12+ (typically 1.0.0 or higher for direct msal-extensions usage, or ensure your azure-identity dependency is updated to a compatible version like 1.10.0 or newer if msal-extensions is a transitive dependency). You might also need to explicitly install a backport of distutils if an upgrade is not immediately possible, but updating is the recommended approach.

error ModuleNotFoundError: No module named 'msal-extensions' ↓

cause This error indicates that the `msal-extensions` library has not been installed in your Python environment or is not accessible in the current Python path.

fix

Install the library using pip: pip install msal-extensions.

error Error: The module '...dpapi.node' was compiled against a different Node.js version using NODE_MODULE_VERSION XX. This version of Node.js requires NODE_MODULE_VERSION YY. Please try re-compiling or re-installing the module.... ↓

cause This error typically occurs with `@azure/msal-node-extensions` when the Node.js version used to install the package (which often compiles native binaries like `dpapi.node` via `node-gyp`) differs from the Node.js version used to run the application.

fix

Recompile or reinstall the module for the current Node.js version. Navigate to your project directory and run npm rebuild or npm install.

error SyntaxError: Named export 'deletePassword' not found. The requested module 'keytar' is a CommonJS module, which may not support all module.exports as named exports. ↓

cause This issue arises when attempting to import `@azure/msal-node-extensions` into an ES Module (ESM) environment in Node.js, because `msal-node-extensions` internally relies on `keytar`, which is a CommonJS module. Direct named imports from CommonJS modules are not always fully supported in ESM.

fix

Instead of direct named imports, import the CommonJS module's default export and destructure the required members. For example, change import { setPassword, getPassword, deletePassword } from 'keytar'; to import pkg from 'keytar'; const { setPassword, getPassword, deletePassword } = pkg;. Alternatively, if possible, ensure your Node.js project is configured to run as a CommonJS module.

Warnings

breaking Ensure that the 'msal' package is installed and up-to-date to avoid compatibility issues. ↓

fix Install or update the 'msal' package using 'pip install msal'.

gotcha The 'CLIENT_ID' and 'CLIENT_SECRET' environment variables must be set for the script to function correctly. ↓

fix Set the 'CLIENT_ID' and 'CLIENT_SECRET' environment variables with appropriate values.

breaking The MSAL configuration failed due to 'ValueError: AADSTS90002: Tenant 'your_tenant_id' not found'. This indicates that the tenant ID or tenant name specified in the authority URL is incorrect or does not exist. Double-check your tenant ID or tenant name. ↓

fix Ensure that the tenant ID or tenant name used in the MSAL authority URL (e.g., in `ConfidentialClientApplication` or `PublicClientApplication`) is correct and corresponds to an existing Azure AD tenant. This value is often provided via an environment variable or configuration file.

breaking The tenant ID provided in the authority URL (e.g., 'your_tenant_id') is invalid or a placeholder was used. Ensure the authority URL contains a valid tenant ID or tenant name. ↓

fix Provide a valid tenant ID or tenant name in the 'authority' URL when initializing the 'ConfidentialClientApplication'. Replace placeholders like 'your_tenant_id' with an actual tenant ID or tenant name.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.26s 37.8M

3.10 slim (glibc) - - 0.21s 38M

3.11 alpine (musl) - - 0.32s 40.2M

3.11 slim (glibc) - - 0.27s 41M

3.12 alpine (musl) - - 0.28s 31.9M

3.12 slim (glibc) - - 0.27s 32M

3.13 alpine (musl) - - 0.26s 31.6M

3.13 slim (glibc) - - 0.26s 32M

3.9 alpine (musl) - - 0.21s 37.8M

3.9 slim (glibc) - - 0.20s 38M

Imports

FilePersistence
```
from msal_extensions.persistence import FilePersistence
```
Ensure correct import path to access FilePersistence class.

Quickstart stale last tested: 2026-04-23

This script demonstrates how to set up token cache persistence using FilePersistence from msal-extensions, initialize a ConfidentialClientApplication with MSAL, and acquire an access token for Microsoft Graph API.

import os
from msal import ConfidentialClientApplication
from msal_extensions.persistence import FilePersistence

# Set up the persistence layer
cache = FilePersistence('my_cache.bin')

# Initialize the MSAL application
app = ConfidentialClientApplication(
    client_id=os.environ.get('CLIENT_ID'),
    client_credential=os.environ.get('CLIENT_SECRET'),
    authority='https://login.microsoftonline.com/your_tenant_id',
    token_cache=cache
)

# Acquire a token
result = app.acquire_token_for_client(scopes=['https://graph.microsoft.com/.default'])

if 'access_token' in result:
    print('Access token acquired successfully.')
else:
    print('Failed to acquire access token.')