Quickstart

Overview

This guide will help you configure django-allauth in your Django project and get a working authentication system running quickly.

This guide assumes you have already installed django-allauth. If not, check the Installation guide first.

Configuration Steps

Follow these steps to integrate django-allauth into your Django project:

Configure Template Context Processors

Add the required context processor to your TEMPLATES setting in settings.py:

settings.py

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # Default Django context processors
                'django.template.context_processors.debug',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
                
                # Required by allauth
                'django.template.context_processors.request',
            ],
        },
    },
]

The django.template.context_processors.request context processor is required by allauth and must be included.

Configure Authentication Backends

Add the allauth authentication backend to your settings.py:

settings.py

AUTHENTICATION_BACKENDS = [
    # Needed to login by username in Django admin, regardless of `allauth`
    'django.contrib.auth.backends.ModelBackend',

    # `allauth` specific authentication methods, such as login by email
    'allauth.account.auth_backends.AuthenticationBackend',
]

Keep the ModelBackend to ensure Django admin login continues to work normally.

Add Apps to INSTALLED_APPS

Add the required allauth apps to INSTALLED_APPS in your settings.py:

Basic Setup
With Social Auth
With MFA

For basic account functionality without social authentication:

settings.py

INSTALLED_APPS = [
    # Django built-in apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',

    # allauth
    'allauth',
    'allauth.account',

    # Your apps
    # ...
]

SITE_ID = 1

For full functionality including social authentication:

settings.py

INSTALLED_APPS = [
    # Django built-in apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',

    # allauth
    'allauth',
    'allauth.account',
    'allauth.socialaccount',

    # Include the providers you want to enable:
    'allauth.socialaccount.providers.google',
    'allauth.socialaccount.providers.github',
    'allauth.socialaccount.providers.facebook',
    # ... add more providers as needed

    # Your apps
    # ...
]

SITE_ID = 1

For multi-factor authentication support:

settings.py

INSTALLED_APPS = [
    # Django built-in apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',

    # allauth
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'allauth.mfa',

    # Your apps
    # ...
]

SITE_ID = 1

The django.contrib.sites framework is required. Make sure to set SITE_ID = 1 in your settings.

Add Account Middleware

Add the account middleware to your MIDDLEWARE setting:

settings.py

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    
    # Add the account middleware:
    'allauth.account.middleware.AccountMiddleware',
]

The AccountMiddleware must be placed after AuthenticationMiddleware.

Configure URL Patterns

Add allauth URLs to your project’s urls.py:

urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('accounts/', include('allauth.urls')),
    # Your other URL patterns...
]

You can use any URL prefix you prefer instead of accounts/. Common alternatives include auth/ or user/.

Run Migrations

Create the necessary database tables:

python manage.py migrate

This will create tables for:

User accounts
Email addresses
Email confirmations
Social accounts (if enabled)
MFA tokens (if enabled)

Configure Basic Settings

Add essential allauth configuration to your settings.py:

settings.py

# Authentication settings
ACCOUNT_AUTHENTICATION_METHOD = 'email'
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = 'mandatory'

# Signup settings
ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']

# Login settings
LOGIN_REDIRECT_URL = '/'
ACCOUNT_LOGOUT_REDIRECT_URL = '/'

Complete Configuration Example

Here’s a complete example of a minimal settings.py configuration:

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = 'your-secret-key-here'
DEBUG = True
ALLOWED_HOSTS = ['127.0.0.1', 'localhost']

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',
    
    # allauth
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
]

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'allauth.account.middleware.AccountMiddleware',
]

ROOT_URLCONF = 'yourproject.urls'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

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

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

SITE_ID = 1

# allauth configuration
ACCOUNT_AUTHENTICATION_METHOD = 'email'
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = 'mandatory'
ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']

LOGIN_REDIRECT_URL = '/'
ACCOUNT_LOGOUT_REDIRECT_URL = '/'

# Email backend (for development)
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

To enable social authentication providers, you need to configure them in your settings:

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'SCOPE': [
            'profile',
            'email',
        ],
        'AUTH_PARAMS': {
            'access_type': 'online',
        },
        'APP': {
            'client_id': 'your-google-client-id',
            'secret': 'your-google-client-secret',
            'key': ''
        }
    }
}

Alternatively, you can configure social apps through the Django admin interface instead of settings.

Testing Your Setup

Start the development server and test your authentication system:

python manage.py runserver

Visit the following URLs to verify everything is working:

Login

http://localhost:8000/accounts/login/

Signup

http://localhost:8000/accounts/signup/

Password Reset

http://localhost:8000/accounts/password/reset/

Admin

http://localhost:8000/admin/

Common Configuration Options

Customize django-allauth behavior with these popular settings:

settings.py

# Allow login by email only
ACCOUNT_AUTHENTICATION_METHOD = 'email'

# Allow login by username only
ACCOUNT_AUTHENTICATION_METHOD = 'username'

# Allow login by either email or username
ACCOUNT_AUTHENTICATION_METHOD = 'username_email'

Email Verification Options

settings.py

# Mandatory email verification
ACCOUNT_EMAIL_VERIFICATION = 'mandatory'

# Optional email verification (email sent but not required)
ACCOUNT_EMAIL_VERIFICATION = 'optional'

# No email verification
ACCOUNT_EMAIL_VERIFICATION = 'none'

Signup Field Configuration

settings.py

# Email and password only
ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']

# Username and password
ACCOUNT_SIGNUP_FIELDS = ['username*', 'password1*', 'password2*']

# Username, email, and password
ACCOUNT_SIGNUP_FIELDS = ['username*', 'email*', 'password1*', 'password2*']

# Email with confirmation (type twice)
ACCOUNT_SIGNUP_FIELDS = ['email*', 'email2*', 'password1*']

Advanced Features

settings.py

# Enable magic link login (login by email code)
ACCOUNT_LOGIN_BY_CODE_ENABLED = True

# Enable password reset by code instead of link
ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED = True

# Enable email verification by code instead of link
ACCOUNT_EMAIL_VERIFICATION_BY_CODE_ENABLED = True

# Prevent account enumeration attacks
ACCOUNT_PREVENT_ENUMERATION = True

# Session remember option
ACCOUNT_SESSION_REMEMBER = None  # Ask user
# ACCOUNT_SESSION_REMEMBER = True  # Always remember
# ACCOUNT_SESSION_REMEMBER = False  # Never remember

Security Settings

settings.py

# Rate limiting (default values shown)
ACCOUNT_RATE_LIMITS = {
    'login_failed': '5/5m',  # 5 failed attempts per 5 minutes
    'change_password': '5/5m/user',
    'reauthenticate': '10/1h/user',
    'reset_password': '20/1d/ip',
    'reset_password_email': '20/1h/email',
    'signup': '20/1d/ip',
}

# Require reauthentication for sensitive operations
ACCOUNT_REAUTHENTICATION_REQUIRED = True
ACCOUNT_REAUTHENTICATION_TIMEOUT = 300  # 5 minutes

Important Security Considerations

Session Engine Compatibilitydjango-allauth is NOT compatible with SESSION_ENGINE set to "django.contrib.sessions.backends.signed_cookies".Signed cookies are signed but not encrypted, whereas allauth stores secrets (e.g. verification codes) in the session.

For production environments, always:

Use HTTPS
Set DEBUG = False
Configure proper email backend (not console)
Enable rate limiting
Use strong SECRET_KEY
Enable account enumeration prevention

Creating a Superuser

Create an admin user to access the Django admin:

python manage.py createsuperuser

You can now:

Access the admin at http://localhost:8000/admin/
Configure social apps
Manage user accounts
View email addresses and verifications

URL Patterns Provided

Once configured, django-allauth provides these URL patterns:

URL Pattern	Description
`/accounts/login/`	User login page
`/accounts/signup/`	User registration page
`/accounts/logout/`	Logout endpoint
`/accounts/password/reset/`	Password reset request
`/accounts/password/change/`	Change password (authenticated)
`/accounts/email/`	Manage email addresses
`/accounts/confirm-email/<key>/`	Email confirmation
`/accounts/social/connections/`	Manage social connections
`/accounts/social/login/<provider>/`	Social login initiation

You don’t need to include django.contrib.auth.urls when using allauth, as it provides all necessary authentication URLs.

Example Project

The django-allauth repository includes a fully functional example project:

# Clone the repository
git clone https://codeberg.org/allauth/django-allauth.git
cd django-allauth/examples/regular-django

# Install dependencies
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Run the server
python manage.py runserver

Visit the live demo at: https://django.demo.allauth.org

Next Steps

Account Configuration

Explore all available configuration options

Social Providers

Set up social authentication providers

Templates

Customize the look and feel

Signals

Hook into authentication events

Get Started

Core Concepts

Social Authentication

Multi-Factor Authentication

Headless API

Identity Provider

Configuration

Guides

Overview

Configuration Steps

Complete Configuration Example

Testing Your Setup

Login

Signup

Password Reset

Admin

Common Configuration Options

Important Security Considerations

Creating a Superuser

URL Patterns Provided

Example Project

Next Steps

Account Configuration

Social Providers

Templates

Signals

Get Started

Core Concepts

Social Authentication

Multi-Factor Authentication

Headless API

Identity Provider

Configuration

Guides

​Overview

​Configuration Steps

​Complete Configuration Example

​Social Provider Configuration

​Testing Your Setup

Login

Signup

Password Reset

Admin

​Common Configuration Options

​Important Security Considerations

​Creating a Superuser

​URL Patterns Provided

​Example Project

​Next Steps

Account Configuration

Social Providers

Templates

Signals

Overview

Configuration Steps

Complete Configuration Example

Social Provider Configuration

Testing Your Setup

Common Configuration Options

Important Security Considerations

Creating a Superuser

URL Patterns Provided

Example Project

Next Steps