Social Authentication

This guide covers how to set up and use social authentication with DRF Auth Kit. Social authentication allows users to log in using their accounts from providers like Google, Facebook, GitHub, and many others.

Prerequisites

API Documentation Setup Required

Before following this guide, complete the API Documentation Setup to configure interactive API documentation (Swagger UI, ReDoc, and DRF Browsable API). This setup is essential for testing the social authentication endpoints described below.

Overview

DRF Auth Kit integrates with Django Allauth to provide comprehensive social authentication support. This integration provides:

  • Multiple Providers: Support for 50+ social authentication providers

  • Protocol Support: Both OAuth2 and OpenID Connect protocols

  • Automatic URL Generation: URLs and views are automatically created for any installed social provider

  • Account Management: Connect/disconnect social accounts to existing users

  • Unified API: Consistent authentication flow for all providers

  • Interactive Documentation: All endpoints automatically documented in your API schema

  • Template Support: Optional HTML templates for browser-based flows

  • Secure by Default: Uses Authorization Code Flow for maximum security and compatibility

Key Advantage: When you include auth_kit.social.urls, the system automatically generates authentication endpoints for any installed Django Allauth social provider configured in your settings or database.

Installation

Social authentication requires additional dependencies:

pip install drf-auth-kit[social]

This installs django-allauth[socialaccount] (>=65.5.0) which includes support for 50+ social authentication providers.

Basic Configuration

Django Settings

# settings.py
INSTALLED_APPS = [
    # Core Django and DRF
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'rest_framework',

    # Allauth (required)
    'allauth',
    'allauth.account',
    'allauth.socialaccount',

    # Social Providers (add as needed)
    'allauth.socialaccount.providers.google',
    # Add other providers as needed - see Django Allauth documentation

    # DRF Auth Kit
    'auth_kit',
    'auth_kit.social',  # Social authentication integration
]

Include Social URLs

# urls.py
urlpatterns = [
    path('api/auth/', include('auth_kit.urls')),
    path('api/auth/social/', include('auth_kit.social.urls')),  # Auto-generates provider endpoints
]

Explore Social Endpoints

Once configured, visit your API documentation to see the automatically generated social authentication endpoints (configured in the Prerequisites section above).

The system automatically creates endpoints for each configured provider. For example, with Google configured:

Social Login Endpoints:

  • POST /api/auth/social/google/ - Google login

Social Connect Endpoints:

  • POST /api/auth/social/google/connect/ - Connect Google account

Account Management:

  • GET /api/auth/social/accounts/ - List connected social accounts

  • DELETE /api/auth/social/accounts/{id}/ - Disconnect social account

Note: Similar endpoints are automatically created for each provider you configure (Facebook, GitHub, LinkedIn, etc.).

Google OAuth Setup

Provider Configuration

# settings.py
SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'SCOPE': ['profile', 'email'],
        'AUTH_PARAMS': {'access_type': 'online'},
        'OAUTH_PKCE_ENABLED': True,
        'FETCH_USERINFO': True,
        'APP': {
            'client_id': 'your-google-client-id',
            'secret': 'your-google-client-secret',
            'key': '',
        }
    },
}

Getting Google OAuth Credentials

  1. Go to Google Cloud Console

  2. Create a new project or select existing one

  3. Enable Google+ API

  4. Create OAuth 2.0 credentials

  5. Add authorized redirect URIs for your domain

Test Google Login

Navigate to POST /api/auth/social/google/ in your API documentation to test the integration.

Social Authentication Flow

DRF Auth Kit supports OAuth2 and OpenID Connect protocols with multiple flow types. However, Authorization Code Flow is strongly recommended and used by default for maximum compatibility and security.

Authorization Code Flow (Recommended - Default)

  1. Frontend redirects user to Google OAuth URL

  2. User authorizes your application

  3. Google redirects back with authorization code

  4. Frontend sends code to POST /api/auth/social/google/

  5. Backend exchanges code for tokens and returns user data

Access Token Flow (Not Recommended)

Note: This flow is provided for compatibility but is not recommended for most use cases due to:

  • Limited provider support

  • Security considerations with token handling in frontend

  • Reduced functionality compared to authorization code flow

  1. Frontend obtains access token directly from provider

  2. Frontend sends token to POST /api/auth/social/google/

  3. Backend validates token and returns user data

Flow Configuration (Keep Default)

Authorization Code Flow is used by default. Only change this if you have specific requirements:

AUTH_KIT = {
    'SOCIAL_LOGIN_AUTH_TYPE': 'code',  # Default: 'code' (recommended)
    # 'SOCIAL_LOGIN_AUTH_TYPE': 'token',  # Not recommended for most cases
}

Social Account Management

Connect Social Account

For logged-in users to connect additional social accounts:

  1. User must be authenticated

  2. Use the appropriate connect endpoint (e.g., POST /api/auth/social/google/connect/)

  3. Provide authorization code or access token

  4. Account gets linked to current user

List Connected Accounts

Use GET /api/auth/social/accounts/ to see all social accounts connected to the current user.

Disconnect Social Account

Remove social account connections using DELETE /api/auth/social/accounts/{id}/.

Adding More Providers

Other Social Providers

DRF Auth Kit supports any provider that Django Allauth supports (50+ providers) with both OAuth2 and OpenID Connect protocols. To add other providers:

  1. Install Provider Package: Add the provider app to INSTALLED_APPS

  2. Configure Provider Settings: Add provider configuration to SOCIALACCOUNT_PROVIDERS

  3. Endpoints Auto-Generated: DRF Auth Kit automatically creates endpoints for each configured provider

Protocol Support:

  • OAuth2: Google, Facebook, GitHub, Twitter, and most traditional providers

  • OpenID Connect: LinkedIn, Microsoft Azure AD, and other OIDC-compliant providers

  • Automatic Detection: DRF Auth Kit handles both protocols transparently

Example with GitHub:

# settings.py
INSTALLED_APPS = [
    # ... existing apps
    'allauth.socialaccount.providers.google',
    'allauth.socialaccount.providers.github',  # Add GitHub
]

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        # ... Google configuration (shown above)
    },
    'github': {
        'SCOPE': ['user:email'],
        'VERIFIED_EMAIL': True,
    },
}

This automatically creates:

  • POST /api/auth/social/github/ - GitHub login

  • POST /api/auth/social/github/connect/ - Connect GitHub account

Provider-Specific Setup

For detailed setup instructions for specific providers, see the Django Allauth Provider Documentation:

Testing Social Authentication

Using API Documentation

  1. Setup Provider: Configure OAuth app with provider

  2. Test Login Flow: Use API documentation to test social login

  3. Test Account Management: Try connecting/disconnecting accounts

  4. Error Scenarios: Test with invalid tokens/codes

Common Test Scenarios

Test these flows in your API documentation:

  • New user social registration

  • Existing user social login

  • Connecting social account to existing user

  • Multiple social accounts per user

  • Disconnecting social accounts

  • Error handling (invalid tokens, provider errors)

Configuration Options

Social Authentication Settings

AUTH_KIT = {
    # OAuth Flow Type
    'SOCIAL_LOGIN_AUTH_TYPE': 'code',              # 'code' or 'token'

    # Account Linking
    'SOCIAL_LOGIN_AUTO_CONNECT_BY_EMAIL': True,    # Auto-link by email
    'SOCIAL_CONNECT_REQUIRE_EMAIL_MATCH': True,    # Require email match for linking

    # Callback URLs
    'SOCIAL_LOGIN_CALLBACK_BASE_URL': '',          # Custom callback URL base
    'SOCIAL_CONNECT_CALLBACK_BASE_URL': '',        # Custom connect callback base

    # Security
    'SOCIAL_HIDE_AUTH_ERROR_DETAILS': True,        # Hide detailed error messages
}

SOCIAL_LOGIN_AUTO_CONNECT_BY_EMAIL Behavior

When SOCIAL_LOGIN_AUTO_CONNECT_BY_EMAIL is True (the default), DRF Auth Kit automatically connects social accounts to existing users with matching email addresses. This enables a seamless experience for users who:

  • Register with email/password, then later login with a social provider using the same email

  • Login with one social provider (e.g., Google), then later login with another provider (e.g., Microsoft) using the same email

Security Model: By enabling this setting, you are trusting your configured social providers to provide accurate email information. Major providers like Google, Microsoft, and GitHub verify user emails before returning them. When a user authenticates via a trusted provider, their social account is automatically linked to any existing account with the same email.

When disabled (False), users attempting social login with an email that already exists in the system will receive an error: “User is already registered with this e-mail address.” They must either:

  • Login with their existing credentials and manually connect the social account

  • Use a different social account

Note: DRF Auth Kit’s SOCIAL_LOGIN_AUTO_CONNECT_BY_EMAIL works independently of Django Allauth’s SOCIALACCOUNT_EMAIL_AUTHENTICATION setting. You do not need to configure both - the auth_kit setting provides a simpler, single-setting approach for REST API applications.

Django Allauth Settings

# Basic allauth configuration (recommended)
SOCIALACCOUNT_AUTO_SIGNUP = True
SOCIALACCOUNT_QUERY_EMAIL = True

# Note: SOCIALACCOUNT_EMAIL_AUTHENTICATION is NOT required when using
# auth_kit's SOCIAL_LOGIN_AUTO_CONNECT_BY_EMAIL setting. Auth Kit handles
# email-based account linking independently for REST API flows.

Frontend Integration

Authorization Code Flow (Recommended)

// Step 1: Redirect user to provider OAuth URL
function redirectToGoogle() {
    const clientId = 'your-google-client-id';
    const redirectUri = 'http://localhost:3000/auth/callback';
    const scope = 'profile email';

    const authUrl = `https://accounts.google.com/oauth/authorize?` +
        `client_id=${clientId}&` +
        `redirect_uri=${redirectUri}&` +
        `scope=${scope}&` +
        `response_type=code&` +
        `access_type=online`;

    window.location.href = authUrl;
}

// Step 2: Handle callback and exchange code for tokens
async function handleGoogleCallback(code) {
    const response = await fetch('/api/auth/social/google/', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ code: code })
    });

    const data = await response.json();

    if (response.ok) {
        // Login successful - store tokens if needed
        console.log('Social login successful:', data);
        return data;
    } else {
        throw new Error('Social login failed');
    }
}

Access Token Flow (Not Recommended - For Compatibility Only)

// Note: This approach is not recommended for most applications
// Use Authorization Code Flow instead for better security and compatibility

// Using Google's JavaScript SDK (legacy approach)
async function loginWithGoogleToken() {
    // Get token from Google SDK
    const authInstance = gapi.auth2.getAuthInstance();
    const googleUser = await authInstance.signIn();
    const accessToken = googleUser.getAuthResponse().access_token;

    // Send to DRF Auth Kit
    const response = await fetch('/api/auth/social/google/', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ access_token: accessToken })
    });

    return await response.json();
}

Connect Social Account

// Connect social account to existing user
async function connectGoogleAccount(authCode) {
    const response = await fetch('/api/auth/social/google/connect/', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${userAccessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ code: authCode })
    });

    return await response.json();
}

Advanced Topics

Custom Social Views

Override social authentication components:

AUTH_KIT = {
    'SOCIAL_LOGIN_VIEW': 'myapp.views.CustomSocialLoginView',
    'SOCIAL_CONNECT_VIEW': 'myapp.views.CustomSocialConnectView',
    'SOCIAL_ACCOUNT_VIEW_SET': 'myapp.viewsets.CustomSocialAccountViewSet',
}

Custom Provider Configuration

For providers not included in django-allauth, or custom OAuth2 providers:

SOCIALACCOUNT_PROVIDERS = {
    'openid_connect': {
        'APPS': [
            {
                'provider_id': 'your_custom_provider',
                'name': 'Your Custom Provider',
                'client_id': 'your-client-id',
                'secret': 'your-client-secret',
                'settings': {
                    'server_url': 'https://your-provider.com/oauth',
                },
            }
        ]
    }
}

Error Handling

Common error scenarios:

  • Invalid authorization codes

  • Expired access tokens

  • Provider configuration errors

  • Email linking conflicts

  • Rate limiting

Security Considerations

  • Always use HTTPS in production

  • Validate redirect URIs properly

  • Store client secrets securely

  • Monitor for suspicious social login activity

  • Consider rate limiting social authentication attempts

Next Steps

Now that you understand social authentication:

  • Test Integration: Use /api/docs/ to test social authentication flows

  • Configure Providers: Set up OAuth apps with your chosen social providers

  • Frontend Integration: Implement social login in your frontend application

  • Account Management: Build user interfaces for connecting/disconnecting social accounts

  • Multi-Factor Authentication: Multi-Factor Authentication (MFA) - Combine social auth with MFA for enhanced security

  • Customization: Customization - Customize social authentication behavior

  • Future Features: Upcoming Features - See planned social authentication enhancements

Provider Documentation

For provider-specific OAuth setup and configuration:

Each provider has detailed setup instructions including OAuth app creation, configuration parameters, and specific requirements.