django-auth-adfs

1.16.0 verified Mon Apr 27 auth: no python

A Django authentication backend for Microsoft ADFS and Azure AD. Implements OAuth2/OpenID Connect flows for single sign-on. Current version 1.16.0 supports Django 3.2-6.0 and Python 3.9+. Release cadence is irregular, approximately 2-3 minor versions per year.

pip install django-auth-adfs

Common errors

error ImportError: cannot import name 'AuthenticationBackend' from 'django_auth_adfs' ↓

cause Incorrect import path. The backend is in the submodule `backend`.

fix

Use from django_auth_adfs.backend import AuthenticationBackend

error django.core.exceptions.ImproperlyConfigured: The AUTH_ADFS setting must be a dict. ↓

cause Missing or incorrectly defined AUTH_ADFS dictionary in Django settings.

fix

Add AUTH_ADFS dictionary with required keys (SERVER, CLIENT_ID, etc.)

error requests.exceptions.ConnectionError: HTTPSConnectionPool(host='adfs.yourorg.com', port=443): Max retries exceeded ↓

cause Network connectivity issue or incorrect SERVER setting (missing https:// or typo).

fix

Ensure AUTH_ADFS['SERVER'] includes 'https://' and is reachable from your server.

Warnings

breaking Django 6 support added in 1.16.0; older versions (<1.16) may break on Django 6. ↓

fix Upgrade to django-auth-adfs>=1.16.0

breaking Django 3.2 and 4.0/4.1 dropped in 1.14.0; will cause import errors or compatibility issues. ↓

fix Use django-auth-adfs<1.14.0 if stuck on older Django

gotcha AssertionError or AttributeError due to missing or malformed JWT token. Often caused by misconfigured AUDIENCE or CLAIM_MAPPING. ↓

fix Verify the token's 'aud' claim matches AUTH_ADFS['AUDIENCE'] exactly; check claim mapping keys match token fields.

gotcha Redirect loop on login if SERVER setting does not include protocol (https://). The library does not automatically add https. ↓

fix Set SERVER to 'https://adfs.yourorg.com' (with https://)

Imports

AuthenticationBackend

wrong

from django_auth_adfs import AuthenticationBackend

correct

from django_auth_adfs.backend import AuthenticationBackend

Backend is in the backend module, not package root

views

from django_auth_adfs.views import OAuth2CallbackView, OAuth2LoginView

Correct import for OAuth2 views

Quickstart

Configure ADFS backend, claim mapping, and include OAuth2 URLs.

# settings.py
INSTALLED_APPS = [
    ...
    'django_auth_adfs',
    'django_auth_adfs.drf',  # optional: for DRF integration
]

AUTHENTICATION_BACKENDS = [
    'django_auth_adfs.backend.AuthenticationBackend',
    'django.contrib.auth.backends.ModelBackend',
]

AUTH_ADFS = {
    "SERVER": "adfs.yourorg.com",
    "CLIENT_ID": "your-client-id",
    "RELYING_PARTY_ID": "your-rp-id",
    "AUDIENCE": "microsoft:identityserver:your-rp-id",
    "CA_BUNDLE": "/etc/ssl/certs/ca-certificates.crt",
    "CLAIM_MAPPING": {"first_name": "given_name", "last_name": "family_name", "email": "email"},
}

# urls.py
from django.urls import path, include
urlpatterns = [
    path('oauth2/', include('django_auth_adfs.urls')),
]

# Quick login: go to /oauth2/login