Quickstart

Get up and running with django-allauth in minutes

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:

1. 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.

2. 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.

3. Add Apps to INSTALLED_APPS

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

   Basic Setup

   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
   

   With Social Auth

   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
   

   With MFA

   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.

4. 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.

5. 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/.

6. 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)
7. 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:

settings.py (Basic)

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'

Social Provider Configuration

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

Google Provider

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:

Login Method Configuration

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 Compatibility

django-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:

1. Access the admin at http://localhost:8000/admin/
2. Configure social apps
3. Manage user accounts
4. 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