Django Advanced Authentication

A production-ready, clean, and well-tested JWT-based authentication system built with Django & Django REST Framework.

This project demonstrates modern Django best practices including custom user model, email verification, token blacklisting, structured logging, Docker support, high test coverage, and clean project structure.

Features

• Custom User Model

  • Email as the unique identifier
  • UUID primary key
  • Email verification status

• JWT Authentication

  • Access + Refresh tokens (SimpleJWT)
  • Custom token refresh with automatic blacklisting of old tokens
  • Token blacklisting on logout / rotation / password change

• User Management API

  • User registration
  • Profile retrieve / update (owner or staff only)
  • Change password
  • Logout (blacklist refresh token)
  • Email verification via signed token

• Security & Best Practices

  • Strict permission classes (IsOwnerOrStaff, IsAdminUser, etc.)
  • Token blacklist model with cleanup support
  • Structured logging with structlog + django-structlog
  • Environment-based settings (dev / test / prod)
  • Pre-commit hooks (Ruff + formatting)

• Developer Experience

  • Docker & Docker Compose (dev / test / prod)
  • Multi-stage Dockerfile
  • Makefile for common tasks
  • OpenAPI / Swagger documentation (drf-spectacular)
  • High test coverage with pytest + pytest-cov + factories

Tech Stack

Technology	Purpose
Django 5.2	Web framework
Django REST Framework	API layer
SimpleJWT	JWT authentication
PostgreSQL	Database
drf-spectacular	OpenAPI schema & Swagger UI
structlog	Structured logging
pytest + pytest-cov	Testing & coverage
Ruff	Linting & formatting
Docker / Docker Compose	Containerization
pre-commit	Git hooks

Project Structure

..
├── docker-compose*.yml          # Dev / Test / Prod
├── Dockerfile
├── Makefile
├── pyproject.toml
├── requirements.txt
├── logs/                        # Application logs
└── src/
    ├── manage.py
    ├── apps/
    │   └── accounts/            # Custom User + JWT Auth API
    │       ├── api/v1/          # Serializers, ViewSets, URLs
    │       ├── models/          # User & TokenBlacklist
    │       ├── management/      # Custom management commands
    │       └── tests/           # High coverage tests
    ├── config/                  # Settings, logging, gunicorn
    └── core/                    # Shared utilities (email, tokens, permissions)

Quick Start

1. Clone the repository

git clone https://github.com/usgitAz/django_advance_authentication.git
cd django_advance_authentication

2. Environment setup

cp .env.example .env.dev
# Edit .env.dev with your values

3. Run with Docker (recommended)

make dev

This starts the web and PostgreSQL containers.

4. Apply migrations & create superuser

make migrate
make superuser

5. Access the API

• API Base: http://localhost:8000/api/v1/
• Swagger UI: http://localhost:8000/api/docs/
• ReDoc: http://localhost:8000/api/redoc/
• Health check: http://localhost:8000/health/

API Endpoints

Method	Endpoint	Description	Auth
POST	/api/v1/users/	Register new user	Public
GET	/api/v1/users/{id}/	Retrieve user	Owner/Staff
PATCH	/api/v1/users/{id}/	Update user	Owner/Staff
POST	/api/v1/users/change_password/	Change password	Auth
POST	/api/v1/users/logout/	Logout (blacklist refresh token)	Auth
GET	/api/v1/users/verify-email/{token}/	Verify email	Public
POST	/api/v1/token/	Obtain access + refresh token	Public
POST	/api/v1/token/refresh/	Refresh token (with blacklist)	Public

Testing

Run the full test suite with coverage:

# Local
make localtest

# Inside Docker
make test

The project is configured for high test coverage using:

• pytest + pytest-django
• factory_boy + pytest-factoryboy
• Coverage reporting via pytest-cov

Development Commands

make help          # Show all available commands
make local         # Run with Python runserver
make dev           # Run development stack
make test          # Run tests in Docker
make migrate       # Apply migrations
make superuser     # Create superuser
make logs          # View container logs
make clean         # Stop and remove containers + volumes

Code Quality

• Ruff for linting and formatting
• pre-commit hooks enforced
• Clean separation of concerns (API / models / core utilities)
• Type-friendly and well-documented code