Secure Microsoft identity platform authentication helpers built on MSAL for Python.
Table of contents
- Features
- Installation
- Desktop application
- Public-client authentication
- Device-code authentication
- Client-credentials authentication
- Certificate authentication
- Configuration
- Upgrading from 1.4.0b1
- Token-cache security
- Error handling
- Development
- License
Features
- Interactive, silent, device-code, and client-credentials authentication.
- Encrypted, cross-process-safe token persistence through MSAL Extensions.
- Client secrets stored in the operating-system credential manager.
- PFX/P12 and PEM certificate credentials, with GUI creation (90-day default), local validation and optional profile-scoped password storage. See Certificate authentication.
- Exact-path
.envloading; no upward directory search. - Delegated and application scope handling kept separate.
- No filesystem writes or global logging configuration during import.
Installation
python -m pip install azauthlib
Optional first-time setup: To configure your connections using a graphical interface, run the following command in the environment where azauthlib is installed:
azauthlib-app
The GUI is optional. You can instead configure credentials through Python or environment variables, as shown below. See Desktop application for more details.
From a source checkout:
git clone git@github.com:doydl-technologies/azauthlib.git
cd azauthlib
python -m pip install .
Python 3.10 or newer is required.
Desktop application
Open the Connections Manager from a terminal in the environment where azauthlib is installed:
azauthlib-app
Alternatively, run python -m azauthlib.gui.launch with that environment's Python.
No Python code is needed to use the application.
Choose Create app shortcut in the top-right corner of Home or Connections to create a launcher for your user account:
- Windows: an
azauthlib.lnkDesktop shortcut with the application icon. - macOS: an
azauthlib.appDesktop launcher that can also be added to the Dock. - Linux: an applications-menu entry and a Desktop copy when a Desktop folder is available. The desktop environment may require approval before launching the Desktop copy.
Shortcut creation is optional and does not run during installation, import, or startup. Existing files with the same name are not overwritten. These launchers use the current Python environment, rather than bundling Python; keep that environment installed at the same location. If it moves, remove the old launcher and create another from the new environment.
See Startup preferences for optional faster repeat launches, splash-screen behavior and opening the app at login.
Public-client authentication
from azauthlib import Authentication, InteractionRequiredError
auth = Authentication(scopes=["User.Read"])
auth.Build.WithEntry(
client_id="00000000-0000-0000-0000-000000000000",
tenant_id="organizations",
)
try:
result = auth.Silent()
except InteractionRequiredError:
result = auth.Interactive()
print(result["token_source"])
# Use auth.access_token only where an Authorization header is required.
Silent authentication does not unexpectedly launch a browser. Pass
fallback_to_interactive=True if that behavior is explicitly desired.
Device-code authentication
auth = Authentication(scopes=["Files.Read"])
auth.Build.WithEntry(client_id="...", tenant_id="organizations")
result = auth.DeviceCodeFlow(webbrowser_enabled=True)
MSAL controls polling and expiration. The method blocks until authentication completes or fails.
Client-credentials authentication
Microsoft requires the /.default resource scope for client credentials:
auth = Authentication()
auth.Build.WithEntry(
client_id="...",
tenant_id="...",
client_secret="...",
)
result = auth.ClientCredentials()
# Default scope: https://graph.microsoft.com/.default
For production workloads, prefer a certificate or workload identity federation over a shared secret when your deployment architecture supports it.
Configuration
Environment variables are supported:
export CLIENT_ID="..."
export TENANT_ID="..."
export CLIENT_SECRET="..." # confidential clients only
auth = Authentication(scopes=["User.Read"])
auth.Build.WithOSEnv()
WithOSEnv() treats mapping values strictly as environment-variable names. Use WithEntry() for
literal values.
The optional configuration application stores the client ID and tenant ID in azauthlib's platform
configuration directory. Client secrets go to the operating-system keyring, never the .env file:
azauthlib-app
The application supports named profiles for multiple Microsoft Entra app registrations. After the splash screen, choose Microsoft Graph on the Home page to open the Connections Manager. Add, edit, optionally test, remove, and set the active connection there. Other service cards are previews and cannot continue yet. Information buttons open a contextual-help shelf that pushes the workspace aside. It explains profiles, authentication methods, connection testing, and where to find your Entra app registration's Tenant/Directory ID, Client/Application ID, and client secret. The active info button is dimmed and disabled while its topic is open. Close the shelf with its close button, Got it, or Escape, or select another topic.
The Test connection icon is blue for untested saved credentials, green for the last successful
test, and red for the last failed test. Changing credentials resets the indicator; renaming a
connection does not. Canceling a retest preserves the previous completed result. This is test
history, not a guarantee that authentication or every Microsoft Graph operation will work now.
History stores only outcomes and signed, opaque credential fingerprints, with its signing key
in the OS credential manager. Tests do not persist tokens or client secrets. When history storage
is unavailable, results are kept for the current session only.
The Default profile uses .env and msal-cache.bin directly in the current configuration
and cache directories. Every additional profile receives its own public configuration file
and encrypted MSAL token cache; client secrets
remain in the operating-system keyring. Create and select profiles in the configuration app, or
manage the active profile in Python:
from azauthlib import Authentication, create_profile, select_profile
from azauthlib.credentials import save_configuration
profile = create_profile("Accounting")
save_configuration(
profile=profile,
client_id="00000000-0000-0000-0000-000000000000",
tenant_id="organizations",
auth_method="interactive",
)
select_profile("Accounting")
# Explicit profile selection is recommended when several applications share a process.
auth = Authentication(profile="Accounting", scopes=["User.Read"])
auth.Build.Default()
Passing profile= avoids depending on whichever profile is currently selected in the GUI.
Upgrading from 1.4.0b1
On Windows, the default configuration and cache directories no longer include the additional vendor directory. Existing settings are not automatically migrated. To upgrade safely:
- Close azauthlib and any applications using its token cache.
- Back up the existing configuration and cache directories. The previous Windows configuration
directory is normally
%LOCALAPPDATA%\DOYDL Technologies\azauthlib; its cache is normally theCachesubdirectory. Keep these backups private because they contain authentication data. - Install the update, run
azauthlib-app, and recreate the required connections using the saved tenant ID, client ID, and authentication method. The new configuration directory is normally%LOCALAPPDATA%\azauthlib, with its cache in theCachesubdirectory. Do not delete the old files until the new connections have been verified. - Test each connection and sign in again where required. Client secrets remain in the operating system's keyring, keyed by client ID. If a secret cannot be retrieved, enter it again through the application; never put it in a public configuration file.
macOS and Linux keep their platform-specific configuration/cache roots. The Default profile uses the existing root-level files there; additional profiles use separate files. An explicitly supplied environment-file or token-cache path remains under the caller's control.
New authentication instances use the active profile unless profile= is supplied. Select an
explicit profile for applications that must not follow desktop selection changes. After all
profiles have been removed, create a profile before constructing an authentication instance.
Removing a profile archives its known local files; it does not revoke issued tokens or erase
shared client secrets from the keyring.
Token-cache security
Encrypted persistence is the default and fails closed when the OS encryption provider is unavailable. On Linux, ensure an appropriate Secret Service/LibSecret backend is configured.
Plaintext fallback requires an explicit opt-in:
auth = Authentication(allow_plaintext_cache=True)
Only use that option when file permissions and the threat model have been independently reviewed.
Error handling
Authentication methods return the successful MSAL result dictionary. Failures raise:
AuthenticationErrorfor identity platform or protocol errors.InteractionRequiredErrorwhen silent authentication cannot continue.TokenCacheSecurityErrorwhen secure persistence cannot be established.
Error logs include error codes and correlation IDs, not full response dictionaries or tokens.
Development
python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
bandit -c pyproject.toml -r src
pip-audit --skip-editable
pytest
python -m build
twine check dist/*
See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md. Maintainers should also follow RELEASING.md.
The tutorial screenshot index can be opened locally after cloning the repository. Its screenshots are documentation assets, not installed runtime files.
For a connection-free animation preview from an editable checkout:
python .github/desktop/preview_add_connection_animation.py --loop
License
Apache License 2.0. Microsoft, Azure, Entra, and Microsoft Graph are trademarks of Microsoft and are not affiliated with or endorsed by this project.
Metadata
Release files for azauthlib 5.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| azauthlib-5.0.0.tar.gz | 4.1 MB | Without provenance | Details for azauthlib-5.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| azauthlib-5.0.0-py3-none-any.whl | Python 3 | none | any | Details for azauthlib-5.0.0-py3-none-any.whl |
Total release size: 8.7 MB
Release files / azauthlib-5.0.0.tar.gz
| Download URL | azauthlib-5.0.0.tar.gz |
|---|---|
| Size | 4.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
27b316eaaa0b9afe497d24f362172f00b555068d1621eaa7b84e9c0ee67bfe94
|
|
BLAKE2b-256 checksum How to use checksums |
4cb849083d2f35a71e357fa6c5321038d1fe3b180e8383747491c6118f0b0a87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / azauthlib-5.0.0-py3-none-any.whl
| Download URL | azauthlib-5.0.0-py3-none-any.whl |
|---|---|
| Size | 4.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fdf3ce62721604302128ba1d2c7e0979208200c40549b941fef29a2ee1885921
|
|
BLAKE2b-256 checksum How to use checksums |
551d78083e523c514bc9b4d53dc1aec52cb6358fc31168bcd3b2e596d254fde6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Security for azauthlib 5.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.