64 lines
3.6 KiB
Markdown
64 lines
3.6 KiB
Markdown
# 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)
|
|
1) **Install packages** (venv active):
|
|
```bash
|
|
pip install 'django-allauth[socialaccount,mfa]' python-dotenv djangorestframework django-cors-headers fido2 python3-openid Pillow pyyaml
|
|
```
|
|
2) **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).
|
|
3) **Environment file** `.env.development` in project root:
|
|
```
|
|
GOOGLE_CLIENT_ID=
|
|
GOOGLE_CLIENT_SECRET=
|
|
```
|
|
4) **URLs** in project `urls.py`:
|
|
```python
|
|
path('accounts/', include('allauth.urls')),
|
|
path('_allauth/', include('allauth.headless.urls')),
|
|
```
|
|
5) **Sanity checks & DB**:
|
|
```bash
|
|
python manage.py check
|
|
python manage.py migrate
|
|
```
|
|
6) **Optional validation tests** (after cloning `django-allauth` sibling to project):
|
|
```bash
|
|
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.
|