django-allauth

What this skill does

## Overview

This skill configures django-allauth in headless mode for React/Vue/frontend applications. Unlike traditional Django authentication that renders server-side templates, headless mode exposes authentication as REST APIs, making it ideal for single-page applications (SPAs) and mobile apps.

**What this skill provides:**
- Complete django-allauth setup with headless API endpoints
- Multi-factor authentication (TOTP, WebAuthn, recovery codes)
- Social authentication (Google OAuth example included)
- CORS configuration for cross-origin frontend communication
- Email verification and password reset workflows
- Session management for authenticated users

**End result:** A Django backend with secure, production-ready authentication APIs that the React frontend can consume via HTTP requests.

## Prerequisites

Before using this skill, ensure:
- Django project is created
- Virtual environment is created

## Setup Steps

To set up django-allauth in headless mode for React, follow these steps:
1. Install Django-Allauth headless mode Dependencies
2. Configure `settings.py`
3. Create Environment File `.env.development`
4. Add URL routes to `urls.py`
5. Check Django Configuration
6. Run migrations
7. Validate Installation with Tests

---

### Step 1: Activate virtual environment and Install Django-Allauth headless mode Dependencies

Install the required packages for authentication, social login, MFA, and cross-origin requests:

```bash
source venv/bin/activate
pip install 'django-allauth[socialaccount,mfa]' python-dotenv djangorestframework django-cors-headers fido2 python3-openid Pillow pyyaml
```

**Package purposes:**
- `django-allauth[socialaccount,mfa]` - Core authentication with social providers and multi-factor auth
- `python-dotenv` - Load environment variables from `.env` files
- `djangorestframework` - REST API framework (required by allauth headless)
- `django-cors-headers` - Enable cross-origin requests from React frontend
- `fido2` - WebAuthn/passkey support for passwordless authentication
- `python3-openid` - OpenID authentication support for social providers
- `Pillow` - Image processing library (required for avatar/profile images)
- `pyyaml` - YAML parser (required for allauth configuration)

---

### Step 2: Configure `settings.py`

### Find the settings file using Glob tool with pattern "**/*settings.py"

**Editing steps for `settings.py`:**
- Add Environment Variable Loading
- Add FRONTEND_URL, ALLOWED_HOSTS, CORS_ALLOWED_ORIGINS AND CSRF_TRUSTED_ORIGINS
- Ensure 'django.template.context_processors.request' is included in the template context processors list
- Update INSTALLED_APPS
- Update MIDDLEWARE
- Add Django-Allauth Configuration settings to the end of the file

#### Add Environment Variable Loading 

Insert these lines at the end of the existing imports (top of the file):

```python
import os
from dotenv import load_dotenv
load_dotenv('.env.development')
```

#### Ensure 'django.template.context_processors.request' is included in the template context processors list

**Why:** Django-allauth requires access to the request object in templates for authentication flows.

Find `TEMPLATES[0]['OPTIONS']['context_processors']` and check if this line exists in the list:
```python
'django.template.context_processors.request',
```

**If missing:** Add it to the end of the `context_processors` list

#### Update INSTALLED_APPS

Find the `INSTALLED_APPS` list and append the following to the end of the list:
```python

    # Authentication and user management (django-allauth)
    'allauth',
    'allauth.account',
    'allauth.socialaccount',

    # Providers
    'allauth.socialaccount.providers.google',

    # Multi-Factor Authentication (MFA)
    'allauth.mfa',

    # Headless API support for allauth
    'allauth.headless',
    'allauth.usersessions',
```

The end result should look similar to:
```python
INSTALLED_APPS = [
    # Django core apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # Cross-Origin Resource Sharing
    'corsheaders',

    # REST API support
    'rest_framework',

    # Authentication and user management (django-allauth)
    'allauth',
    'allauth.account',
    'allauth.socialaccount',

    # Providers
    'allauth.socialaccount.providers.google',

    # Multi-Factor Authentication (MFA)
    'allauth.mfa',

    # Headless API support for allauth
    'allauth.headless',
    'allauth.usersessions',
]
```

#### Update MIDDLEWARE

Find the `MIDDLEWARE` list. After `'django.contrib.messages.middleware.MessageMiddleware',`, add:
```python
"allauth.account.middleware.AccountMiddleware",
```

**Critical middleware order requirements:**
- `CorsMiddleware` must come AFTER `SessionMiddleware` and BEFORE `CommonMiddleware` to properly handle CORS headers before request processing
- `AccountMiddleware` must come AFTER `MessageMiddleware` to access session-based authentication state

**Expected result:**
```python
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'corsheaders.middleware.CorsMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'allauth.account.middleware.AccountMiddleware',  # ← Add here
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]
```

#### Add Django-Allauth Configuration settings to the end of the file

**Location:** At the very end of `settings.py`

**Action:** Append all of the following authentication and MFA configuration:

```python

AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',
    'allauth.account.auth_backends.AuthenticationBackend',
]

# Account settings
ACCOUNT_EMAIL_VERIFICATION = "mandatory"  # Require email verification before login
ACCOUNT_LOGIN_METHODS = {'email'}  # Use email instead of username for login
ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']
ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE = False
ACCOUNT_LOGIN_BY_CODE_ENABLED = True  # Enable passwordless login via email code
ACCOUNT_EMAIL_VERIFICATION_BY_CODE_ENABLED = True

# Multi-Factor Authentication settings
MFA_SUPPORTED_TYPES = ["totp", "webauthn", "recovery_codes"]
MFA_PASSKEY_LOGIN_ENABLED = True  # Enable passwordless WebAuthn login
MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN = True if DEBUG else False  # Allow localhost in dev
MFA_PASSKEY_SIGNUP_ENABLED = True

# Headless mode configuration
HEADLESS_ONLY = True  # Disable server-side templates, use API endpoints only
HEADLESS_FRONTEND_URLS = {
    "account_confirm_email": f"{FRONTEND_URL}/account/verify-email/{{key}}",
    "account_reset_password": f"{FRONTEND_URL}/account/password/reset",
    "account_reset_password_from_key": f"{FRONTEND_URL}/account/password/reset/key/{{key}}",
    "account_signup": f"{FRONTEND_URL}/account/signup",
    "socialaccount_login_error": f"{FRONTEND_URL}/account/provider/error",
}

# Provider specific settings
SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'APP': {
            'client_id': os.environ.get('GOOGLE_CLIENT_ID'),
            'secret': os.environ.get('GOOGLE_CLIENT_SECRET'),
            'key': ''
        },
        'FETCH_USERINFO': True,
    }
}

EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'
EMAIL_FILE_PATH = BASE_DIR / 'sent_emails'  
```

**Key configuration notes:**
- `HEADLESS_ONLY = True` disables Django's template-based authentication views and forces API-only mode
- `HEADLESS_FRONTEND_URLS` tells the backend where to redirect users in email links (e.g., password reset, email verification)
- Social providers can be added/removed from `SOCIALACCOUNT_PROVIDERS` as needed
- Email backend is set to console for development; change to SMTP for production

--