django-admin-2fa-plus 0.1.0
Two-Factor Authentication for Django Admin with TOTP, backup codes, trusted devices, and more.
License: MIT
Requires Python: >=3.6

# Django Admin 2FA Plus

[![PyPI version](https://badge.fury.io/py/django-admin-2fa-plus.svg)](https://pypi.org/project/django-admin-2fa-plus/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Django Versions](https://img.shields.io/badge/Django-3.2%2B-blue)](https://www.djangoproject.com/)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/your-username/django-admin-2fa-plus)

**Django Admin 2FA Plus** is a secure, easy-to-use Two-Factor Authentication package for Django Admin. It provides TOTP-based verification (Google Authenticator, Authy, etc.), recovery codes, and optional trusted devices.

---

## 🌟 Features

- 🔐 Secure Django Admin with 2FA
- 📱 TOTP Authentication (Google Authenticator, Authy, 1Password, etc.)
- 🔑 One-time use Backup Recovery Codes
- 📩 Optional Email OTP fallback (configurable)
- 🧩 Admin interface to manage TOTP Devices
- 🎛️ Trusted Device support (via cookies)
- 🎨 Customizable templates
- ⚙️ Middleware-based enforcement
- ⚡ Works with Django 3.2+

---

## 📦 Installation

```bash
pip install django-admin-2fa-plus
```

Add it to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    "django_admin_2fa_plus",
]
```

Add the middleware near the top of your middleware stack:

```python
MIDDLEWARE = [
    "django_admin_2fa_plus.middleware.Admin2FAMiddleware",
    ...
]
```

Include the URLs:

```python
# urls.py
path("admin-2fa/", include("django_admin_2fa_plus.urls")),
```

Run migrations:

```bash
python manage.py migrate
```

---

## 🚀 Quick Start

1. Log in to Django Admin.
2. Go to `/admin-2fa/setup/` to begin TOTP setup.
3. Scan the QR code using your authenticator app.
4. Enter the generated code to confirm.
5. Save the backup codes displayed — each can be used once.
6. Done! 2FA is now required to access the admin area.

---

## ⚙️ Optional Settings

You can override the default behavior using these settings in your Django `settings.py`:

| Setting | Default | Description |
|--------|---------|-------------|
| `ADMIN_2FA_REDIRECT_URL` | `/admin/` | URL to redirect to after successful verification |
| `ADMIN_2FA_TOTP_DIGITS` | `6` | Number of digits for the TOTP code |
| `ADMIN_2FA_TOTP_STEP` | `30` | Step size in seconds for TOTP code rotation |
| `ADMIN_2FA_TOTP_ALGORITHM` | `'sha1'` | Algorithm used for TOTP (`'sha1'`, `'sha256'`, `'sha512'`) |
| `ADMIN_2FA_BACKUP_CODES_COUNT` | `10` | Number of backup codes generated |
| `ADMIN_2FA_TRUSTED_DEVICE_DAYS` | `30` | Days to trust a device when user selects "Remember this device" |
| `ADMIN_2FA_ENABLE_EMAIL_OTP` | `False` | Enable fallback email OTP support |
| `ADMIN_2FA_EMAIL_SENDER` | `None` | Sender address for email OTP |
| `ADMIN_2FA_EMAIL_SUBJECT` | `'Your login code'` | Subject line for email OTP |
| `ADMIN_2FA_EMAIL_TEMPLATE` | `None` | Path to custom HTML template for email OTP |

---

## 🧪 Testing

Unit test are pending


## 🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -am 'Add new feature'`
4. Update code, if needed, as per pre-commit logs
5. Push to the branch: `git push origin feature/my-feature`
6. Open a Pull Request

Please follow PEP8, isort and write tests for any new functionality.

---

## 📬 Support

For questions, bug reports, or feature requests, please open an [issue](https://github.com/zahid-ali-shah/django-admin-2fa-plus/issues) on GitHub.

---

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

Secure your Django Admin with ease ✨