django-simple-auth-pkg 1.0.0
A simple, customizable Django authentication package with JWT support, email verification, and password management
License: MIT
Requires Python: >=3.8
Keywords: django, authentication, jwt, rest-framework, email-verification, password-reset

# 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](#features)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Configuration Reference](#configuration-reference)
5. [Custom User Model Support](#custom-user-model-support)
6. [API Documentation](#api-documentation)
7. [Template Customization](#template-customization)
8. [Email Verification](#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](QUICKSTART.md)

Or run the setup checker:
```bash
python manage.py simpleauth_check
```

## Installation

1.  **Install via pip**:
    ```bash
    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:
    ```python
    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:
    ```python
    from django.urls import path, include

    urlpatterns = [
        # ...
        path('auth/', include('simple_auth.urls')),
    ]
    ```

4.  **Run Migrations**:
    ```bash
    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:**
```python
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**:
    ```python
    # 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**:
    ```python
    AUTH_USER_MODEL = 'accounts.CustomUser'
    SIMPLE_AUTH_USER_FIELDS = ['phone_number', 'avatar']
    ```

35.  **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](QUICKSTART.md)
2. See [Examples](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**:
  ```json
  {
    "username": "jdoe",
    "email": "jdoe@example.com",
    "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**:
  ```json
  {
    "username": "jdoe@example.com", // 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**:
  ```json
  {
    "old_password": "oldpassword",
    "new_password": "newpassword"
  }
  ```

### 4. Password Reset Request
- **Endpoint**: `POST /auth/api/password-reset/`
- **Payload**: `{"email": "jdoe@example.com"}`

### 5. Password Reset Confirm
- **Endpoint**: `POST /auth/api/password-reset-confirm/`
- **Payload**:
  ```json
  {
    "uidb64": "<uid from email>",
    "token": "<token from email>",
    "new_password": "newpassword"
  }
  ```

### 6. Resend Verification Email
- **Endpoint**: `POST /auth/api/resend-verification/`
- **Payload**: `{"email": "jdoe@example.com"}`

## 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:**
```html
{% 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.