Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

azauthlib

Secure Microsoft identity platform authentication helpers built on MSAL for Python.

Beta: APIs may change before the first stable release. Do not deploy a beta upgrade without testing its cache, keyring, and authentication behavior in your environment.

PyPI Python 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.
  • Exact-path .env loading; 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

From a source checkout:

git clone git@github.com:cedricmoorejr/azauthlib.git
cd azauthlib
python -m pip install .

Python 3.10 or newer is required.

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

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:

  • AuthenticationError for identity platform or protocol errors.
  • InteractionRequiredError when silent authentication cannot continue.
  • TokenCacheSecurityError when 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.

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 1.4.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for azauthlib 1.4.0b1
File Size Uploaded Provenance Actions
azauthlib-1.4.0b1.tar.gz 41.8 kB Without provenance Details for azauthlib-1.4.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for azauthlib 1.4.0b1
File Interpreter ABI Platform Actions
azauthlib-1.4.0b1-py3-none-any.whl Python 3 none any Details for azauthlib-1.4.0b1-py3-none-any.whl

Total release size: 87.8 kB

Release files / azauthlib-1.4.0b1.tar.gz

Download URL azauthlib-1.4.0b1.tar.gz
Size 41.8 kB
Tags Source
SHA-256 checksum
How to use checksums
22beaa72800b235570cd1895e3830209274f947d5377ef36af9ef1a4dece15f9
BLAKE2b-256 checksum
How to use checksums
f416d7433a66018905e01476ab6283c0840dc1c2ef16df3b0436d93a1cda533d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.16

Release files / azauthlib-1.4.0b1-py3-none-any.whl

Download URL azauthlib-1.4.0b1-py3-none-any.whl
Size 46.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
073d539be4c46679626b83f26f9a3d01b1e07dff567bc5cbec1fbf72e86de6e6
BLAKE2b-256 checksum
How to use checksums
3b9e6ff98d6800e0da9a9365a2d0ce2325445ad71bb3ef203226d476d44ed7f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.16

Security for azauthlib 1.4.0b1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page