Django Allauth (Headless) Skill

Headless authentication setup for Django backends that serve React/Vue/mobile frontends. Adds django-allauth with MFA, social login, CORS, and REST endpoints—no server-rendered auth pages.

What This Skill Delivers

Installs auth stack: django-allauth[socialaccount,mfa], djangorestframework, django-cors-headers, fido2, python3-openid, Pillow, pyyaml, python-dotenv.
Configures headless mode (HEADLESS_ONLY = True) with frontend redirect URLs for email verification, password reset, signup, and social errors.
Enables MFA (TOTP + WebAuthn/passkeys + recovery codes) and Google OAuth example.
Sets CORS/CSRF for a separate HTTPS frontend (FRONTEND_URL), uses session/JWT-friendly middleware ordering.
Adds REST URL prefixes: accounts/ (admin/backend) and _allauth/ (headless API).
Provides validation harness to run the official headless allauth tests (76 core cases) via scripts/validate_allauth_tests.sh and detailed coverage notes in references/test-validation-guide.md.

Skill Contents

SKILL.md — step-by-step build instructions (install deps → settings.py edits → .env → URLs → checks → migrations → tests).
scripts/validate_allauth_tests.sh — helper to run core allauth tests after cloning django-allauth.
references/test-validation-guide.md — explains test categories, required pytest versions, and troubleshooting.

Prerequisites

Existing Django project with virtualenv.
FRONTEND_URL to point at your HTTPS SPA (e.g., https://localhost:5173).

Setup Summary (see SKILL.md for exact edits)

Install packages (venv active):

pip install 'django-allauth[socialaccount,mfa]' python-dotenv djangorestframework django-cors-headers fido2 python3-openid Pillow pyyaml

settings.py changes:
- Load env vars: from dotenv import load_dotenv; load_dotenv('.env.development').
- Add CORS/CSRF hosts: FRONTEND_URL, ALLOWED_HOSTS, CORS_ALLOWED_ORIGINS, CSRF_TRUSTED_ORIGINS.
- Ensure django.template.context_processors.request is in TEMPLATES[0]['OPTIONS']['context_processors'].
- INSTALLED_APPS add: corsheaders, rest_framework, allauth, allauth.account, allauth.socialaccount, allauth.socialaccount.providers.google, allauth.mfa, allauth.headless, allauth.usersessions.
- MIDDLEWARE order: keep corsheaders.middleware.CorsMiddleware after SessionMiddleware; add allauth.account.middleware.AccountMiddleware after MessageMiddleware.
- Auth backends + headless/MFA/social/email settings appended at file end (see SKILL.md block).
Environment file .env.development in project root:
```
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
```

URLs in project urls.py:

path('accounts/', include('allauth.urls')),
path('_allauth/', include('allauth.headless.urls')),

Sanity checks & DB:

python manage.py check
python manage.py migrate

Optional validation tests (after cloning django-allauth sibling to project):
```
bash scripts/validate_allauth_tests.sh
```

Outputs/Artifacts

Headless auth APIs ready for SPA use.
MFA-ready user flows (TOTP/WebAuthn/recovery codes).
Dev email backend writes files to sent_emails/ (adjust for production).
Updated requirements.txt (after pip freeze).

Notes & Gotchas

Use pytest <9.0 and pytest-asyncio==0.23.8 for the provided test suite.
Keep middleware order exact to avoid CORS/login issues.
Set MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN = True if DEBUG else False so localhost HTTPS works during development.

3.6 KiB Raw Permalink Blame History