Django Social Auth

Warnings

• breaking Version 5.7.0 integrated with `social_core` using a registry instead of monkey patching. While generally an internal change, custom integrations relying on previous monkey-patching behavior might require adjustments. Always review the changelog for details if you have highly customized setups.
  Fix: Consult `social-auth-core` and `social-auth-app-django` documentation regarding registry usage if your custom code interacts with internal backend registration mechanisms.
• breaking Support for older Django and Python versions has been progressively dropped in recent releases. Version 5.2.0 removed support for Django < 3.2, and 5.5.0 dropped support for additional older Django versions. The library now requires Python >= 3.10 and is compatible with Django versions 4.2, 5.0, 5.1, and 5.2.
  Fix: Ensure your project uses Python >= 3.10 and a supported Django version (e.g., 4.2, 5.0, 5.1, 5.2). Refer to the official documentation for the precise list of currently supported versions.
• gotcha A security vulnerability (CVE-2025-61783) in versions prior to 5.6.0 allowed for potentially unsafe account association via email, even if the `associate_by_email` pipeline was not explicitly enabled. Version 5.6.0 fixed this issue, and also introduced a change where storage now filters for active users; you might need to customize `SOCIAL_AUTH_ACTIVE_USERS_FILTER` if your custom user model lacks an `is_active` field.
  Fix: Upgrade to `social-auth-app-django` version 5.6.0 or higher. Review and potentially customize `SOCIAL_AUTH_ACTIVE_USERS_FILTER` if using a custom user model without an `is_active` field.
• gotcha A security vulnerability (CVE-2024-32879) in versions prior to 5.4.1 addressed improper handling of case sensitivity with MySQL/MariaDB databases, where the default case-insensitive collation could cause different user IDs to match. This could lead to account spoofing.
  Fix: Upgrade to `social-auth-app-django` version 5.4.1 or higher. If using MySQL/MariaDB with an affected version, consider changing the collation of the user ID field as an immediate workaround.
• gotcha SQLite has field length limitations that can cause issues, especially with UIDs from social providers. For production environments, PostgreSQL or MySQL are recommended. If using MySQL InnoDB or SQLite, you might need to add `SOCIAL_AUTH_UID_LENGTH = 223` to your settings to avoid database errors.
  Fix: Use PostgreSQL or MySQL for production. For SQLite/MySQL, set `SOCIAL_AUTH_UID_LENGTH = 223` in `settings.py` if encountering UID length errors.
• gotcha The `SOCIAL_AUTH_PIPELINE` setting, if configured with `social_core.pipeline.social_auth.associate_by_email`, can be insecure. This is because not all social providers validate the user's email address, potentially allowing a malicious user to claim an existing account by registering with a non-validated email on a third-party provider that matches an email in your system.
  Fix: Only enable `associate_by_email` if you are certain that all your configured social providers rigorously validate email addresses. Otherwise, consider alternative association methods or manual verification steps.
• gotcha Sensitive credentials (like `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY` and `SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET`) should never be committed to version control. Always use environment variables or a secure configuration management system.
  Fix: Store all API keys and secrets in environment variables (e.g., using `os.environ.get`) or a secrets management service, and ensure they are excluded from your repository.

Install

• pip install social-auth-app-django Install latest version

Imports

• social_django

  INSTALLED_APPS = ['social_django']

  Required to register the application in Django's settings.
• GoogleOAuth2

  from social_core.backends.google import GoogleOAuth2
  AUTHENTICATION_BACKENDS = ('social_core.backends.google.GoogleOAuth2', ...)

  Example of importing a specific social backend for configuration in AUTHENTICATION_BACKENDS.
• social_django.urls

  from django.urls import include, path
  urlpatterns = [path('oauth/', include('social_django.urls', namespace='social'))]

  Integrates the social authentication URLs into your project's URL configuration.
• SocialAuthExceptionMiddleware

  MIDDLEWARE = [..., 'social_django.middleware.SocialAuthExceptionMiddleware']

  Optional middleware for handling social authentication exceptions and displaying messages.

Quickstart

This quickstart outlines the essential configuration for integrating Google OAuth2 login into a Django project. It covers adding `social_django` to `INSTALLED_APPS` and `MIDDLEWARE`, configuring authentication backends, defining OAuth2 credentials using environment variables, setting redirect URLs, adding context processors for templates, and including the `social_django` URLs. Remember to run `python manage.py migrate` after configuration.

import os

# settings.py
INSTALLED_APPS = [
    # ... existing apps ...
    'django.contrib.auth',
    'django.contrib.sessions',
    'social_django',
]

MIDDLEWARE = [
    # ... existing middleware ...
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'social_django.middleware.SocialAuthExceptionMiddleware',
]

AUTHENTICATION_BACKENDS = (
    'social_core.backends.google.GoogleOAuth2',
    'django.contrib.auth.backends.ModelBackend',
)

SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = os.environ.get('GOOGLE_OAUTH2_KEY', '')
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = os.environ.get('GOOGLE_OAUTH2_SECRET', '')
SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = ['email', 'profile']

LOGIN_URL = '/login/'
LOGIN_REDIRECT_URL = '/'
LOGOUT_REDIRECT_URL = '/'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # ... existing context processors ...
                'social_django.context_processors.backends',
                'social_django.context_processors.login_redirect',
            ],
        },
    },
]

# urls.py
from django.urls import include, path

urlpatterns = [
    path('oauth/', include('social_django.urls', namespace='social')),
    # ... other paths ...
]

# In your login template (e.g., login.html)
# <a href="{% url 'social:begin' 'google-oauth2' %}">Login with Google</a>