django-allauth

Warnings

• breaking Starting with version 65.14.2, IP address detection for rate limiting no longer trusts the `X-Forwarded-For` header by default due to security concerns.
  Fix: You must explicitly configure IP detection in your `settings.py` by setting `ALLAUTH_TRUSTED_PROXY_COUNT` (number of proxies in front of Django) or `ALLAUTH_TRUSTED_CLIENT_IP_HEADER` (e.g., 'HTTP_CF_CONNECTING_IP' for Cloudflare) to match your deployment architecture. Failing to do so will likely break rate limiting.
• breaking Support for older Python and Django versions has been progressively dropped. Version 64.x dropped Python 3.7 support (requiring 3.8+), and version 65.15.0 dropped Python 3.8 and 3.9 support. Version 63.x dropped Django 3.2 support (requiring Django 4.2+).
  Fix: Before upgrading `django-allauth`, ensure your Python version is >=3.10 and your Django version is >=4.2 LTS (or 5.0+ for the latest allauth versions). Refer to the official compatibility matrix for exact requirements.
• breaking Version 64.x introduced significant changes to the template system, moving towards an element-based styling approach. Custom templates might not render correctly or benefit from new features.
  Fix: Review your custom `allauth` templates. It is recommended to migrate them to use the new element-based system. Alternatively, for a quick fix, ensure your `TEMPLATES` settings do not automatically discover `allauth` templates before your custom ones, allowing your overrides to take precedence.
• gotcha `django-allauth` is explicitly NOT compatible with `SESSION_ENGINE` set to `django.contrib.sessions.backends.signed_cookies`.
  Fix: Do not use `django.contrib.sessions.backends.signed_cookies` as your `SESSION_ENGINE` if you are using `django-allauth`. It stores secrets (like verification codes) in the session, and signed cookies do not encrypt the data, making it insecure.
• breaking As of version 65.3.1, social account functionality requires installing `django-allauth` with the `[socialaccount]` extra. A basic `pip install django-allauth` will no longer include social account dependencies.
  Fix: If you use social logins, ensure you install `django-allauth` using `pip install "django-allauth[socialaccount]"` (and specific provider extras if needed, e.g., `[socialaccount,github]`). Update your `requirements.txt` or `pyproject.toml` accordingly.
• breaking For Okta and NetIQ providers (65.13.0+), the identifier field for `SocialAccount.uid` was switched from `preferred_username` to `sub` due to `preferred_username` being mutable.
  Fix: If you rely on these providers and need existing accounts to link, you will need to manually migrate `SocialAccount.uid` based on the `sub` field in `SocialAccount.extra_data`, or if certain of your use case, set `"uid_field": "preferred_username"` in the relevant `SocialApp.settings`.

Install

• pip install django-allauth Basic installation (without social accounts or headless API)
• pip install "django-allauth[socialaccount]" With social account providers (most common)
• pip install "django-allauth[headless]" With headless API support (e.g., for JWT)

Imports

• allauth

  INSTALLED_APPS = ['allauth', ...]

  Primary application entry for core functionality.
• allauth.account

  INSTALLED_APPS = ['allauth.account', ...]

  Required for regular (username/email/password) account management.
• allauth.socialaccount

  INSTALLED_APPS = ['allauth.socialaccount', ...]

  Required for social login functionality.
• allauth.urls

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

  Includes all necessary authentication, registration, and account management URLs.
• AuthenticationBackend

  from allauth.account.auth_backends import AuthenticationBackend

  While ModelBackend is often kept for Django admin, allauth requires its own backend for proper functionality, especially for email authentication or social logins. Both should be in AUTHENTICATION_BACKENDS.
• DefaultAccountAdapter

  from allauth.account.adapter import DefaultAccountAdapter

  Used for customizing various aspects of account management behavior.

Quickstart

To quickly set up `django-allauth`, first add the necessary apps (`django.contrib.sites`, `allauth`, `allauth.account`, and optionally `allauth.socialaccount` and providers) to your `INSTALLED_APPS`. Configure `SITE_ID=1`. Update `AUTHENTICATION_BACKENDS` to include `allauth.account.auth_backends.AuthenticationBackend`. Ensure `django.template.context_processors.request` is in `TEMPLATES`. Add `allauth.account.middleware.AccountMiddleware` to `MIDDLEWARE`. Finally, include `allauth.urls` in your project's `urls.py` under the `/accounts/` path. Basic settings for email authentication and redirection are also common. Remember to run `python manage.py makemigrations` and `python manage.py migrate` after configuration.

import os

# settings.py
# Add to INSTALLED_APPS (order matters, 'django.contrib.sites' and 'allauth' apps come after Django's built-in apps)
INSTALLED_APPS = [
    # ... django defaults
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount', # Optional: if using social logins
    # ... add specific social providers here, e.g., 'allauth.socialaccount.providers.google',
]

SITE_ID = 1 # Must be set to 1 for allauth to function correctly

AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend', # Required for Django admin
    'allauth.account.auth_backends.AuthenticationBackend', # allauth specific backend
]

# Required context processor for allauth templates
TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(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',
            ],
        },
    },
]

# allauth specific settings
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_USERNAME_REQUIRED = False
ACCOUNT_SIGNUP_EMAIL_ENTER_WITHOUT_REQUEST = True # Enable instant signup with email
ACCOUNT_AUTHENTICATION_METHOD = 'email' # Allow login with email, not username
ACCOUNT_EMAIL_VERIFICATION = 'mandatory' # Or 'optional', 'none'
ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS = 1 # How long email verification links are valid
LOGIN_REDIRECT_URL = '/'
ACCOUNT_LOGOUT_REDIRECT_URL = '/'

# Add allauth middleware
MIDDLEWARE = [
    # ... other middlewares
    'allauth.account.middleware.AccountMiddleware',
]

# For testing email in development
if os.environ.get('DJANGO_SETTINGS_MODULE') == 'your_project.settings': # Example check
    EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

# urls.py (in your project's main urls.py)
from django.contrib import admin
from django.urls import path, include

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