Authentication

The User Model based on Email for authentication

A custom user model CustomUser is implemented that uses email as the primary identifier instead of username. This model is seamlessly integrated with Django Allauth for authentication.

By using a custom user model from the start, the boilerplate provides greater flexibility for extending user-related functionality. This is a best practice recommended by Django, as changing the user model after project initialization requires complex database migrations.

Django-allauth

PyBoilerplate leverages django-allauth, a comprehensive authentication library widely adopted in the Django ecosystem. This production-ready solution delivers secure local authentication, seamless OAuth 2.0 integration with major providers (Google, Facebook, GitHub), robust email verification workflows, and essential security features including CSRF protection - all through a highly customizable interface.

Common Authentication URLs

Below are the most frequently used authentication endpoints. For a complete list, set DEBUG=True in your .env file and visit any non-existent URL - Django's 404 page will display all available URLs in your project.

# Login/Logout
/accounts/login/          # Login page (name: account_login)
/accounts/logout/         # Logout page (name: account_logout)

# Registration
/accounts/signup/         # Registration page (name: account_signup)

# Password Management
/accounts/password/reset/             # Initialize password reset (name: account_reset_password)
/accounts/password/reset/done/        # Reset initiated confirmation (name: account_reset_password_done)
/accounts/password/reset/key/<key>/   # Reset form from email (name: account_reset_password_from_key)
/accounts/password/reset/key/done/    # Reset completion (name: account_reset_password_from_key_done)
/accounts/password/change/            # Change password (name: account_change_password)

# Email Management
/accounts/email/                      # Email management (name: account_email)
/accounts/confirm-email/<key>/        # Email confirmation (name: account_confirm_email)
/accounts/confirm-email/              # Email verification sent (name: account_email_verification_sent)

# Social Accounts
/accounts/social/connections/         # Social connections (name: socialaccount_connections)

Usage in Templates

Reference these URLs in your templates using:

<a href="{% url 'account_login' %}">Login</a>
<a href="{% url 'account_signup' %}">Sign Up</a>

Configure Login and Logout Redirection Urls

You can modify redirection URLs after user log in or log out.

# settings.py
LOGIN_REDIRECT_URL = "app_features:feature_1"
LOGOUT_REDIRECT_URL = "app_main:home"

Email Verification Settings

Control how email verification works in your application:

# settings.py
ACCOUNT_EMAIL_VERIFICATION = "mandatory"

• "mandatory": Users must verify their email before they can log in
• "optional": Users can log in without verification, but are encouraged to verify
• "none": Email verification is disabled

Manage Social Account with Django-allauth

Configure Social Accounts

Google OAuth is pre-configured in this starter kit. Obtain your credentials from the Google Cloud Console and configure them in .env file. For detailed instructions on creating OAuth credentials, refer to this guide.

# settings.py
SOCIALACCOUNT_PROVIDERS = {
    # OAuth 2.0 app credentials from Google Cloud Console
    'google': {
        'APP': {
            'client_id': env("GOOGLE_CLIENT_ID"),  # Your Google OAuth client ID
            'secret': env("GOOGLE_SECRET_KEY"),  # Your Google OAuth client secret
            'key': ''  # Not used for Google OAuth
        },
        ...
    },
}

Add other Social Accounts

PyBoilerplate comes pre-configured with Google authentication, but you can easily extend it to support additional social providers like Microsoft, GitHub, Facebook, and others.

# settings.py

INSTALLED_APPS = [
    # existing apps...
    'allauth.socialaccount.providers.google',  # already included

    'allauth.socialaccount.providers.discord',
    'allauth.socialaccount.providers.github',
    'allauth.socialaccount.providers.facebook',
    'allauth.socialaccount.providers.instagram',
    'allauth.socialaccount.providers.linkedin',
    'allauth.socialaccount.providers.linkedin_oauth2',
    'allauth.socialaccount.providers.microsoft',
    'allauth.socialaccount.providers.paypal',
    'allauth.socialaccount.providers.pinterest',
    'allauth.socialaccount.providers.shopify',
    'allauth.socialaccount.providers.slack',
    'allauth.socialaccount.providers.snapchat',
    'allauth.socialaccount.providers.telegram',
    'allauth.socialaccount.providers.twitch',
    'allauth.socialaccount.providers.twitter',
    'allauth.socialaccount.providers.twitter_oauth2',
    ...

    # add other providers as needed, full list here: https://docs.allauth.org/en/latest/installation/quickstart.html
]

• Add the provider configuration to SOCIALAACOUNT_PROVIDERS in settings.py
• Each provider requires specific OAuth credentials and settings (follow django-allauth documentation for specific configuration)

# Example for Github

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        ...
    },
    'github': {
        'APP': {
            'client_id': env("GITHUB_OAUTH_CLIENT_ID"),
            'secret': env("GITHUB_OAUTH_CLIENT_SECRET"),
            'key': ''
        },
        'SCOPE': ['read:user'],
        ...
    }
}

To display the login button for newly added social provider, update the template at templates/socialaccount/snippets/provider_list.html.

<!-- templates/socialaccount/snippets/provider_list.html -->

{% get_providers as socialaccount_providers %}

{% for provider in socialaccount_providers %}
    {% if provider.id == 'google' %}
        <button class="provider-button google">
            <svg class="h-5 w-5"><!-- Google icon --></svg>
        </button>
    {% elif provider.id == 'github' %}
        <button class="provider-button github">
            <svg class="h-5 w-5"><!-- GitHub icon --></svg>
        </button>
    {% endif %}
{% endfor %}

Each provider needs a corresponding conditional block in the template to ensure proper rendering. The provider ID should match the one configured in SOCIALACCOUNT_PROVIDERS.