Social Account Configuration

Configuration Methods

django-allauth supports two methods for configuring social providers:

Settings-based: Define configuration in settings.py
Database-based: Create SocialApp instances via Django admin

Avoid Mixing Methods: Don’t configure the same provider using both methods simultaneously, as this will cause a MultipleObjectsReturned exception.

Settings-Based Configuration

Define providers in your settings.py:

SOCIALACCOUNT_PROVIDERS = {
    "github": {
        # Provider-level settings
        "VERIFIED_EMAIL": True,
        
        # App credentials (optional if using Django admin)
        "APPS": [
            {
                "client_id": "your-github-client-id",
                "secret": "your-github-secret",
                "key": "",
                "settings": {
                    # App-specific settings
                    "scope": ["user", "repo"],
                },
            },
        ],
        
        # Default settings for all apps
        "SCOPE": ["user"],
    },
    "google": {
        "APPS": [
            {
                "client_id": "your-google-client-id",
                "secret": "your-google-secret",
                "settings": {
                    "scope": ["profile", "email"],
                    "auth_params": {
                        "access_type": "online",
                    },
                },
            },
        ],
    },
}

Benefits

Secrets managed in environment variables or secret management systems
Version controlled configuration (without secrets)
Simpler deployment and CI/CD workflows

Database-Based Configuration

Create SocialApp instances via Django admin at /admin/socialaccount/socialapp/:

Navigate to Social applications
Click “Add social application”
Fill in the form:
- Provider: Select from dropdown
- Name: Display name (your choice)
- Client id: From provider’s developer console
- Secret key: From provider’s developer console
- Key: Usually left blank
- Sites: Select applicable sites (if using django.contrib.sites)
- Settings: JSON field for provider-specific settings

Benefits

No code changes needed to update credentials
Multi-tenant support via Django sites framework
Non-technical staff can manage configurations

Security Consideration: Database-based configuration stores secrets in your database. Ensure proper database security, encryption at rest, and access controls.

Global Settings

All settings are prefixed with SOCIALACCOUNT_ in your settings.py.

SOCIALACCOUNT_ADAPTER

Default: "allauth.socialaccount.adapter.DefaultSocialAccountAdapter" Specifies the adapter class for customizing behavior.

SOCIALACCOUNT_ADAPTER = 'myapp.adapters.MySocialAccountAdapter'

SOCIALACCOUNT_AUTO_SIGNUP

Default: True Attempt to bypass the signup form by using fields retrieved from the social provider (username, email). If a conflict arises (duplicate email), the signup form still appears.

SOCIALACCOUNT_AUTO_SIGNUP = True

SOCIALACCOUNT_EMAIL_AUTHENTICATION

Default: False When enabled, users logging in via a social provider with a verified email that matches an existing local account will be logged into that local account, even without a prior connection.

Security Risk: Only enable for fully trusted providers. An untrustworthy provider could fabricate social account data to access any local account.

# Enable globally (not recommended)
SOCIALACCOUNT_EMAIL_AUTHENTICATION = True

# Enable per-provider (recommended)
SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'EMAIL_AUTHENTICATION': True
    }
}

SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT

Default: False When email authentication is applied, controls whether the social account is automatically connected to the local account.

False: Local account remains unchanged; future logins require email authentication each time
True: Social account is connected; future logins work even if the email changes

SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT = True

SOCIALACCOUNT_EMAIL_VERIFICATION

Default: ACCOUNT_EMAIL_VERIFICATION Email verification method for social accounts. Inherits from account settings by default.

from allauth.account.models import EmailVerificationMethod

SOCIALACCOUNT_EMAIL_VERIFICATION = EmailVerificationMethod.OPTIONAL

SOCIALACCOUNT_EMAIL_REQUIRED

Default: "email*" in ACCOUNT_SIGNUP_FIELDS Require email address when signing up with a social account.

SOCIALACCOUNT_EMAIL_REQUIRED = True

SOCIALACCOUNT_QUERY_EMAIL

Default: Same as SOCIALACCOUNT_EMAIL_REQUIRED Request email address from the provider (e.g., using OpenID AX or OAuth scopes).

SOCIALACCOUNT_QUERY_EMAIL = True

SOCIALACCOUNT_FORMS

Default:

{
    'disconnect': 'allauth.socialaccount.forms.DisconnectForm',
    'signup': 'allauth.socialaccount.forms.SignupForm',
}

Override default forms.

SOCIALACCOUNT_FORMS = {
    'disconnect': 'myapp.forms.CustomDisconnectForm',
    'signup': 'myapp.forms.CustomSocialSignupForm',
}

SOCIALACCOUNT_LOGIN_ON_GET

Default: False Controls whether social login endpoints (e.g., /accounts/google/login/) accept GET requests to initiate authentication.

Security Best Practice: Keep this False to require POST requests and prevent CSRF attacks.

SOCIALACCOUNT_LOGIN_ON_GET = False

SOCIALACCOUNT_STORE_TOKENS

Default: False Store OAuth access tokens in the database. Required if you need to make API calls on behalf of users.

Tokens are only stored when the social account is stored. This doesn’t work with EMAIL_AUTHENTICATION unless EMAIL_AUTHENTICATION_AUTO_CONNECT is also enabled.

SOCIALACCOUNT_STORE_TOKENS = True

Access tokens later:

from allauth.socialaccount.models import SocialToken

token = SocialToken.objects.get(account__user=user, account__provider='google')
access_token = token.token
refresh_token = token.token_secret  # For OAuth2

SOCIALACCOUNT_REQUESTS_TIMEOUT

Default: 5 Timeout in seconds for upstream requests to providers.

SOCIALACCOUNT_REQUESTS_TIMEOUT = 10

SOCIALACCOUNT_SOCIALACCOUNT_STR

Default: str of user object Customize the string representation of SocialAccount.

def my_socialaccount_str(socialaccount):
    return f"{socialaccount.user.email} ({socialaccount.provider})"

SOCIALACCOUNT_SOCIALACCOUNT_STR = my_socialaccount_str

SOCIALACCOUNT_ONLY

Default: False Disable all local account functionality. Users can only authenticate via social providers.

SOCIALACCOUNT_ONLY = True

SOCIALACCOUNT_OPENID_CONNECT_URL_PREFIX

Default: "oidc" URL path prefix for OpenID Connect providers. With default settings, a provider with ID foo uses /accounts/oidc/foo/login/.

SOCIALACCOUNT_OPENID_CONNECT_URL_PREFIX = "openid"

Provider-Specific Configuration

Each provider supports specific configuration options via SOCIALACCOUNT_PROVIDERS.

Common OAuth2 Settings

Most OAuth2 providers support these settings:

SOCIALACCOUNT_PROVIDERS = {
    'provider_name': {
        # OAuth scopes to request
        'SCOPE': ['scope1', 'scope2'],
        
        # Additional auth parameters
        'AUTH_PARAMS': {
            'param_name': 'param_value',
        },
        
        # Whether emails from this provider are verified
        'VERIFIED_EMAIL': True,
        
        # Enable PKCE (OAuth2.1)
        'OAUTH_PKCE_ENABLED': True,
    }
}

App-Level Settings

Settings can also be configured per app:

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'APPS': [
            {
                'client_id': 'prod-client-id',
                'secret': 'prod-secret',
                'settings': {
                    # These override provider-level settings
                    'scope': ['profile', 'email', 'calendar.readonly'],
                    'auth_params': {
                        'access_type': 'offline',  # Request refresh token
                    },
                },
            },
        ],
        # Provider-level defaults
        'SCOPE': ['profile', 'email'],
    }
}

Example Configurations

Google with Offline Access

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'APPS': [
            {
                'client_id': os.environ['GOOGLE_CLIENT_ID'],
                'secret': os.environ['GOOGLE_SECRET'],
                'settings': {
                    'scope': ['profile', 'email'],
                    'auth_params': {
                        'access_type': 'offline',
                        'prompt': 'consent',
                    },
                },
            },
        ],
        'OAUTH_PKCE_ENABLED': True,
    }
}

GitHub with Custom Scopes

SOCIALACCOUNT_PROVIDERS = {
    'github': {
        'APPS': [
            {
                'client_id': os.environ['GITHUB_CLIENT_ID'],
                'secret': os.environ['GITHUB_SECRET'],
            },
        ],
        'SCOPE': ['user', 'repo', 'read:org'],
        'VERIFIED_EMAIL': True,
    }
}

Multiple OpenID Connect Providers

SOCIALACCOUNT_PROVIDERS = {
    'openid_connect': {
        'OAUTH_PKCE_ENABLED': True,
        'APPS': [
            {
                'provider_id': 'company-sso',
                'name': 'Company SSO',
                'client_id': 'company-client-id',
                'secret': 'company-secret',
                'settings': {
                    'server_url': 'https://sso.company.com',
                },
            },
            {
                'provider_id': 'partner-sso',
                'name': 'Partner SSO',
                'client_id': 'partner-client-id',
                'secret': 'partner-secret',
                'settings': {
                    'server_url': 'https://sso.partner.com',
                    'token_auth_method': 'client_secret_post',
                },
            },
        ],
    }
}

SAML Configuration

SOCIALACCOUNT_PROVIDERS = {
    'saml': {
        'APPS': [
            {
                'name': 'Acme Inc SSO',
                'provider_id': 'urn:acme.com',
                'client_id': 'acme-inc',  # Organization slug
                'settings': {
                    'attribute_mapping': {
                        'uid': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier',
                        'email': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
                        'email_verified': 'http://schemas.auth0.com/email_verified',
                    },
                    'idp': {
                        'entity_id': 'urn:acme.com',
                        'metadata_url': 'https://acme.com/saml/metadata',
                    },
                },
            },
        ],
    }
}

Environment Variables

Best practice for managing secrets:

import os

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'APPS': [
            {
                'client_id': os.environ.get('GOOGLE_CLIENT_ID'),
                'secret': os.environ.get('GOOGLE_SECRET'),
            },
        ],
    },
    'github': {
        'APPS': [
            {
                'client_id': os.environ.get('GITHUB_CLIENT_ID'),
                'secret': os.environ.get('GITHUB_SECRET'),
            },
        ],
    },
}

In .env file:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_SECRET=your-google-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_SECRET=your-github-secret

Multi-Tenant Configuration

Using Django sites framework for different configurations per domain:

# Enable sites framework
INSTALLED_APPS = [
    'django.contrib.sites',
    # ...
]

SITE_ID = 1

Create separate SocialApp instances via admin and assign to different sites. Each site can have different credentials for the same provider.

Get Started

Core Concepts

Social Authentication

Multi-Factor Authentication

Headless API

Identity Provider

Configuration

Guides

​Configuration Methods

​Settings-Based Configuration

​Benefits

​Database-Based Configuration

​Benefits

​Global Settings

​SOCIALACCOUNT_ADAPTER

​SOCIALACCOUNT_AUTO_SIGNUP

​SOCIALACCOUNT_EMAIL_AUTHENTICATION

​SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT

​SOCIALACCOUNT_EMAIL_VERIFICATION

​SOCIALACCOUNT_EMAIL_REQUIRED

​SOCIALACCOUNT_QUERY_EMAIL

​SOCIALACCOUNT_FORMS

​SOCIALACCOUNT_LOGIN_ON_GET

​SOCIALACCOUNT_STORE_TOKENS

​SOCIALACCOUNT_REQUESTS_TIMEOUT

​SOCIALACCOUNT_SOCIALACCOUNT_STR

​SOCIALACCOUNT_ONLY

​SOCIALACCOUNT_OPENID_CONNECT_URL_PREFIX

​Provider-Specific Configuration

​Common OAuth2 Settings

​App-Level Settings

​Example Configurations

​Google with Offline Access

​GitHub with Custom Scopes

​Multiple OpenID Connect Providers

​SAML Configuration

​Environment Variables

​Multi-Tenant Configuration

​Next Steps

Providers

Advanced Usage

Configuration Methods

Settings-Based Configuration

Benefits

Database-Based Configuration

Benefits

Global Settings

SOCIALACCOUNT_ADAPTER

SOCIALACCOUNT_AUTO_SIGNUP

SOCIALACCOUNT_EMAIL_AUTHENTICATION

SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT

SOCIALACCOUNT_EMAIL_VERIFICATION

SOCIALACCOUNT_EMAIL_REQUIRED

SOCIALACCOUNT_QUERY_EMAIL

SOCIALACCOUNT_FORMS

SOCIALACCOUNT_LOGIN_ON_GET

SOCIALACCOUNT_STORE_TOKENS

SOCIALACCOUNT_REQUESTS_TIMEOUT

SOCIALACCOUNT_SOCIALACCOUNT_STR

SOCIALACCOUNT_ONLY

SOCIALACCOUNT_OPENID_CONNECT_URL_PREFIX

Provider-Specific Configuration

Common OAuth2 Settings

App-Level Settings

Example Configurations

Google with Offline Access

GitHub with Custom Scopes

Multiple OpenID Connect Providers

SAML Configuration

Environment Variables

Multi-Tenant Configuration

Next Steps