dj-auth

A reusable Django app providing production-ready authentication out of the box:

  • Email login — email/password auth via django-allauth, no username required
  • Passkeys — WebAuthn/FIDO2 passkey login (biometrics, hardware keys)
  • TOTP / 2FA — authenticator app support with recovery codes
  • Social auth — Google and GitHub OAuth preconfigured, others easy to add
  • Polished UI — Tailwind CSS templates for login, signup, MFA settings, and more
  • Zero models — no migrations; drop it into any project without touching your schema
  • System checks — warns you at startup if required dependencies are misconfigured

Quick Start

1. Install

# From PyPI (published as "ybz-dj-auth"; the importable package is still dj_auth)
pip install ybz-dj-auth

# Or install directly from GitHub:

# Latest commit on main
pip install git+https://github.com/damycra/dj-auth.git

# Specific tagged release (recommended for reproducible builds)
pip install git+https://github.com/damycra/dj-auth.git@v0.1.0

# Or download the wheel from a GitHub Release and install locally
pip install ybz_dj_auth-0.2.1-py3-none-any.whl

2. Add to INSTALLED_APPS

Important: dj_auth must appear before allauth and all allauth.* entries. Django's template loader searches apps in order — if allauth comes first, its own unstyled built-in templates shadow dj_auth's styled overrides. manage.py check will warn you (dj_auth.W004) if the ordering is wrong.

INSTALLED_APPS = [
    # ... Django built-ins ...
    "django.contrib.sites",       # required by allauth

    "dj_auth",                    # must come before allauth

    "allauth",
    "allauth.account",
    "allauth.socialaccount",      # optional: social login
    "allauth.mfa",                # optional: MFA / passkeys

    # ... your apps ...
]

allauth.socialaccount and allauth.mfa are genuinely optional: the login and signup pages detect whether they are installed and simply omit the social-login buttons / passkey button when they're not. manage.py check emits a warning (dj_auth.W001 / dj_auth.W002) so you know the feature is unavailable.

3. Configure MIDDLEWARE

Add AccountMiddleware after SessionMiddleware:

MIDDLEWARE = [
    ...
    "django.contrib.sessions.middleware.SessionMiddleware",
    ...
    "allauth.account.middleware.AccountMiddleware",
]

4. Configure AUTHENTICATION_BACKENDS

AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",           # keep for admin
    "allauth.account.auth_backends.AuthenticationBackend", # required by allauth
]

5. Include URLs

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

urlpatterns = [
    path("accounts/", include("dj_auth.urls")),
    # ... your other URLs ...
]

6. Run migrations

python manage.py migrate

That's it. Visit /accounts/login/ to see the login page.

Configuration

dj_auth injects sensible defaults on startup via AppConfig.ready(). These are standard allauth and Django settings — no special DJ_AUTH_* namespace. Override any of them in your project's settings.py using the normal allauth setting names.

Setting Default Description
ACCOUNT_LOGIN_METHODS {"email"} Login with email only (no username)
ACCOUNT_SIGNUP_FIELDS ["email*", "password1*", "password2*"] Signup form fields
ACCOUNT_EMAIL_VERIFICATION "optional" "mandatory", "optional", or "none"
LOGIN_REDIRECT_URL "/" Where to go after login
LOGOUT_REDIRECT_URL "/" Where to go after logout
MFA_SUPPORTED_TYPES ["totp", "recovery_codes", "webauthn"] Enabled MFA methods
MFA_PASSKEY_LOGIN_ENABLED True Show passkey login button
MFA_PASSKEY_SIGNUP_ENABLED False Allow passkey signup (requires mandatory email verification)
MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN True Allow HTTP in development — set to False in production
SOCIALACCOUNT_PROVIDERS {} Social provider credentials (see below)
SITE_ID 1 Django sites framework site ID

Template Overriding

dj_auth ships templates inside the package (dj_auth/templates/). Django's template loader checks project-level DIRS first, so you can override any template by placing a file at the same path in your project's template directory.

Overriding base.html

The main layout is base.html. Key blocks:

Block Required Purpose
content yes Main page content — all auth pages render here
head_title no Page <title> text
extra_head no Additional <head> content (CSS links, meta tags)
nav no Entire navigation bar
nav_logo_href no Logo link href (default: /)
nav_logo_content no Logo icon + site name HTML
nav_links no Right-side nav items
footer no Page footer
extra_body no Scripts before </body>

To customise the layout, create templates/base.html in your project (which takes priority over the package's version via Django's DIRS setting). You can start from scratch or copy dj_auth/templates/base.html from the package as a starting point. Do not use {% extends "base.html" %} in your override — that's circular.

Example — minimal base.html keeping dj_auth's Tailwind styles but adding your own nav:

{# myproject/templates/base.html #}
<!DOCTYPE html>
<html lang="en">
<head>
  <title>{% block head_title %}My App{% endblock %}</title>
  <script src="https://cdn.tailwindcss.com"></script>
  {% block extra_head %}{% endblock %}
</head>
<body>
  <nav><!-- your nav here --></nav>
  <main>{% block content %}{% endblock %}</main>
  {% block extra_body %}{% endblock %}
</body>
</html>

Overriding allauth's internal pages

allauth's built-in pages (TOTP setup, WebAuthn management, etc.) extend allauth/layouts/base.html. To make them match your project's branding:

{# myproject/templates/allauth/layouts/base.html #}
{% extends "base.html" %}

Tailwind CSS

Templates use the Tailwind CSS CDN for zero-configuration development. For production:

  1. Install Tailwind: npm install -D tailwindcss
  2. Configure content paths in tailwind.config.js: 
    content: [
  "./templates/**/*.html",
  // Include dj_auth's package templates:
  "<path-to-venv>/lib/python3.x/site-packages/dj_auth/templates/**/*.html",
]
  3. Compile: npx tailwindcss -o static/css/main.css --minify
  4. Override extra_head in your base.html: 
    {% block extra_head %}
<link rel="stylesheet" href="{% static 'css/main.css' %}">
{% endblock %}

Social Providers

Login/signup buttons are rendered only for providers that are actually usable: a provider whose APP has an empty client_id (e.g. credentials left blank in your .env) is hidden automatically, so you can keep provider apps in INSTALLED_APPS and placeholder config in settings without showing dead buttons. The buttons live in account/snippets/social_buttons.html, which you can override like any other template.

Google

SOCIALACCOUNT_PROVIDERS = {
    "google": {
        "APP": {
            "client_id": "your-client-id",
            "secret": "your-client-secret",
            "key": "",
        },
        "SCOPE": ["profile", "email"],
        "AUTH_PARAMS": {"access_type": "online"},
    },
}

Add "allauth.socialaccount.providers.google" to INSTALLED_APPS.

GitHub

SOCIALACCOUNT_PROVIDERS = {
    "github": {
        "APP": {
            "client_id": "your-client-id",
            "secret": "your-client-secret",
            "key": "",
        },
        "SCOPE": ["user:email"],
    },
}

Add "allauth.socialaccount.providers.github" to INSTALLED_APPS.

For other providers, see the django-allauth documentation.

MFA / Passkeys

MFA is enabled by default when allauth.mfa is in INSTALLED_APPS. Users manage their security settings at /accounts/2fa/.

Passkey login

Passkeys are enabled by default (MFA_PASSKEY_LOGIN_ENABLED = True). The login page shows a "Sign in with a passkey" button automatically.

Passkey signup

Disabled by default because it requires mandatory email verification:

ACCOUNT_EMAIL_VERIFICATION = "mandatory"
MFA_PASSKEY_SIGNUP_ENABLED = True

Production WebAuthn

For production (HTTPS), remove the insecure origin allowance:

MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN = False

Running the Example App

cd examples/basic
pip install -e ../../        # install dj-auth from source
pip install -r requirements.txt
cp .env.example .env         # edit as needed
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Visit http://localhost:8000 to see the example app.

Running the Test Suite

pip install -e ".[dev]"
pytest

Or with tox (tests against multiple Django versions):

tox

To run just the lint checks:

tox -e lint
# or
ruff check dj_auth tests

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for damycra from gravatar.com damycra

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.13

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ybz_dj_auth-0.2.2.tar.gz (53.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ybz_dj_auth-0.2.2-py3-none-any.whl (38.5 kB view details)

Uploaded Python 3

File details

Details for the file ybz_dj_auth-0.2.2.tar.gz.

File metadata

  • Download URL: ybz_dj_auth-0.2.2.tar.gz
  • Upload date:
  • Size: 53.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ybz_dj_auth-0.2.2.tar.gz
Algorithm Hash digest
SHA256 fb4a7d67a65cd44b00d8fe4804745d6bc4d5f0ad48582bc73fe1973179275a2c
MD5 37cb483ee179a50ea034e2b36331a886
BLAKE2b-256 c176b6bc39e7e0cf756a6d31ca25e1f6fb6783c280592e221ba0a9e79574dd6c

See more details on using hashes here.

Provenance

The following attestation bundles were made for ybz_dj_auth-0.2.2.tar.gz:

Publisher: publish.yml on damycra/dj-auth

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ybz_dj_auth-0.2.2-py3-none-any.whl.

File metadata

  • Download URL: ybz_dj_auth-0.2.2-py3-none-any.whl
  • Upload date:
  • Size: 38.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ybz_dj_auth-0.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 8e09534d4aaef75d177def18f925988d4dd7253db7f6aff2be0acbc8db580f8e
MD5 d004ab032ea0250531b21d6692e1d2bb
BLAKE2b-256 07b5bc2c99b1ac0b0744c0b43c52d1a1973c571af8535fdeaf7de9ade542c1ae

See more details on using hashes here.

Provenance

The following attestation bundles were made for ybz_dj_auth-0.2.2-py3-none-any.whl:

Publisher: publish.yml on damycra/dj-auth

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.2 This release

2 files

0.2.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page