Microsoft Authentication Library Extensions

Common errors

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

• 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: 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`.

• 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

• pip install msal-extensions Install msal-extensions

Imports

• FilePersistence

  from msal_extensions.persistence import FilePersistence

  Ensure correct import path to access FilePersistence class.

Quickstart

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.')