django-simple-auth-pkg 1.0.0

A simple, customizable Django authentication package with JWT support, email verification, and password management

Django Simple Auth

A simple, customizable, and feature-rich authentication package for Django. It provides a complete solution for user registration, login, password management, and email verification, with support for custom user models and JWT authentication.

Table of Contents

1. Features
2. Installation
3. Quick Start
4. Configuration Reference
5. Custom User Model Support
6. API Documentation
7. Template Customization
8. Email Verification

Features

• Flexible Login: Log in with Username, Email, or Phone Number.
• Custom User Model Support: Seamlessly works with custom user models and extra fields (e.g., Avatar, Address).
• JWT Authentication: Built-in API endpoints for modern frontend integration.
• Email Verification: Integrated support for Resend to verify user emails.
• Password Management: Ready-to-use views for Password Reset and Password Change.
• Customizable: Override templates and forms easily.
• Beginner-Friendly: Clear error messages, helpful hints, and comprehensive documentation.

Quick Start

New to Django Simple Auth? Start here! 👉 QUICKSTART.md

Or run the setup checker:

python manage.py simpleauth_check

Installation

1. Install via pip:

   pip install django-simple-auth-pkg
   

   (For local development, navigate to the package directory and run pip install -e .)

2. Add to INSTALLED_APPS: Open your project's settings.py and add:

   INSTALLED_APPS = [
       # ... default django apps ...
       'rest_framework',
       'rest_framework_simplejwt',
       'simple_auth',
       # 'accounts', # Your custom app if you have one
   ]
   

3. Include URLs: Open your project's urls.py and add:

   from django.urls import path, include
   
   urlpatterns = [
       # ...
       path('auth/', include('simple_auth.urls')),
   ]
   

4. Run Migrations:

   python manage.py migrate
   

Quick Start

Once installed, you can access the following views immediately:

• Signup: /auth/signup/
• Login: /auth/login/
• Logout: /auth/logout/
• Password Change: /auth/password-change/
• Password Reset: /auth/password-reset/

Configuration Reference

Add these settings to your settings.py to control the package behavior.

Setting	Default	Description
SIMPLE_AUTH_LOGIN_FIELD	'username'	Field used for login. Options: 'username', 'email', 'phone_number'.
SIMPLE_AUTH_USER_FIELDS	[]	List of extra fields to include in the Signup form (e.g., ['first_name', 'avatar']).
SIMPLE_AUTH_USE_JWT	False	Set to True to enable API endpoints for JWT authentication.
SIMPLE_AUTH_EMAIL_VERIFICATION	False	Set to True to require email verification.
RESEND_API_KEY	None	Your Resend API Key (required if email verification is on).
LOGIN_REDIRECT_URL	'/accounts/profile/'	URL to redirect to after successful login.
LOGOUT_REDIRECT_URL	None	URL to redirect to after logout.

Example Configuration:

SIMPLE_AUTH_LOGIN_FIELD = 'email'
SIMPLE_AUTH_USER_FIELDS = ['first_name', 'last_name', 'avatar']
SIMPLE_AUTH_USE_JWT = True
SIMPLE_AUTH_EMAIL_VERIFICATION = True
RESEND_API_KEY = 're_123456...'
LOGIN_REDIRECT_URL = '/'

Custom User Model Support

This package is designed to work seamlessly with custom user models.

1. Define your model:

   # accounts/models.py
   from django.contrib.auth.models import AbstractUser
   from django.db import models
   
   class CustomUser(AbstractUser):
       phone_number = models.CharField(max_length=15, unique=True)
       avatar = models.ImageField(upload_to='avatars/', blank=True, null=True)
   

2. Update Settings:

   AUTH_USER_MODEL = 'accounts.CustomUser'
   SIMPLE_AUTH_USER_FIELDS = ['phone_number', 'avatar']
   

3. Important: If you have file fields (like avatar), ensure your signup template form has enctype="multipart/form-data".

Troubleshooting

Common Issues

Problem: "No module named 'simple_auth'"
Solution: Install the package: pip install django-simple-auth

Problem: "CSRF token missing or incorrect"
Solution: API endpoints don't need CSRF. Use /api/auth/api/ endpoints, not /api/auth/ (HTML views).

Problem: "Passwords do not match"
Solution: Ensure password and confirm_password are identical in your request.

Problem: "Current password is incorrect"
Solution: Double-check you're entering your current password, not the new one.

Problem: "Password must be at least 8 characters long"
Solution: Use a password with 8 or more characters.

Getting Help

1. Check the Quickstart Guide
2. See Examples
3. Run python manage.py simpleauth_check to verify your setup
4. Open an issue on GitHub

License

MIT

API Documentation

If SIMPLE_AUTH_USE_JWT = True, the following endpoints are available under /auth/api/:

1. Signup

• Endpoint: POST /auth/api/signup/
• Payload:

  {
    "username": "jdoe",
    "email": "[e-mail]",
    "password": "securepassword",
    "confirm_password": "securepassword",
    "phone_number": "1234567890" // Any extra field defined in settings
  }
  

• Response: 201 Created with access and refresh tokens.

2. Login

• Endpoint: POST /auth/api/login/
• Payload:

  {
    "username": "[e-mail]", // Or username/phone based on config
    "password": "securepassword"
  }
  

• Response: 200 OK with access and refresh tokens.

3. Password Change

• Endpoint: POST /auth/api/password-change/
• Headers: Authorization: Bearer <access_token>
• Payload:

  {
    "old_password": "oldpassword",
    "new_password": "newpassword"
  }
  

4. Password Reset Request

• Endpoint: POST /auth/api/password-reset/
• Payload: {"email": "[e-mail]"}

5. Password Reset Confirm

• Endpoint: POST /auth/api/password-reset-confirm/
• Payload:

  {
    "uidb64": "<uid from email>",
    "token": "<token from email>",
    "new_password": "newpassword"
  }
  

6. Resend Verification Email

• Endpoint: POST /auth/api/resend-verification/
• Payload: {"email": "[e-mail]"}

Template Customization

To customize the look and feel, create a directory named simple_auth inside your project's templates directory. You can override any of the following files:

• simple_auth/base.html (Base layout)
• simple_auth/login.html
• simple_auth/signup.html
• simple_auth/password_reset_form.html
• simple_auth/password_reset_done.html
• simple_auth/password_reset_confirm.html
• simple_auth/password_reset_complete.html
• simple_auth/password_change_form.html
• simple_auth/password_change_done.html
• simple_auth/verification_sent.html
• simple_auth/verification_success.html

Example simple_auth/login.html override:

{% extends 'base.html' %}

{% block content %}
<div class="my-custom-login-class">
    <h2>Login to My App</h2>
    <form method="post">
        {% csrf_token %}
        {{ form.as_p }}
        <button type="submit" class="btn btn-primary">Login</button>
    </form>
</div>
{% endblock %}

Email Verification

To enable email verification:

1. Set SIMPLE_AUTH_EMAIL_VERIFICATION = True.
2. Set RESEND_API_KEY = 're_...'.
3. When a user signs up, is_active will be set to False.
4. An email will be sent with a verification link.
5. Clicking the link will activate the user and redirect to the success page.