Add MFA/2FA support via standalone sub-package (#728)

* Adds Skeleton for MFA Support

* Updates Docs + Linting Errors

* Adds pytop test dep

* Logs MFA events

* Guards secret activation

* Signs ephemeral token to couple to a current user

* Solves race condition

* Fixes state issue

* Removes QR code dep

* Migrates MFA docs to MKDocs

* Update dj_rest_auth/mfa/serializers.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update dj_rest_auth/mfa/serializers.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Adds more logging and post param hardening

* Updates README

* Updates test logic to match new behavior

* Sorts imports properly

* Tests MFA with use JWT is enabled

* Prevents TOCTOU race condition

* Updates post params

* Updates post params

* Include last_used_at

* Overhauls/Modernizes Demo

* Prevents timing attack + security related tweaks

* Adds test coverage

* Patches All Auth for CVE-2026-27982

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: iMerica

README.md

@@ -14,6 +14,7 @@ Secure drop-in authentication endpoints for Django REST Framework. Works seamles
 
 - Login, logout, password change, password reset
 - User registration with email verification
+- Built-in MFA/2FA support (TOTP + recovery codes)
 - JWT authentication with HTTP-only cookies
 - Social auth (Google, GitHub, Facebook) via django-allauth
 - Fully customizable serializers
@@ -129,6 +130,21 @@ urlpatterns = [
 ]
 ```
 
+## MFA / 2FA
+
+```bash
+pip install 'dj-rest-auth[with-mfa]'
+```
+
+MFA ships as an opt-in sub-package (`dj_rest_auth.mfa`) with:
+
+- TOTP login challenge flow
+- Recovery codes
+- Security-focused defaults (short-lived MFA tokens, activation confirmation)
+
+See the guide for setup and endpoint details:  
+[MFA Guide](https://dj-rest-auth.readthedocs.io/en/latest/guides/mfa/)
+
 ## Documentation
 
 Full documentation at **[dj-rest-auth.readthedocs.io](https://dj-rest-auth.readthedocs.io/)**
@@ -137,6 +153,7 @@ Full documentation at **[dj-rest-auth.readthedocs.io](https://dj-rest-auth.readt
 - [API Endpoints](https://dj-rest-auth.readthedocs.io/en/latest/api/endpoints/)
 - [JWT & Cookies Guide](https://dj-rest-auth.readthedocs.io/en/latest/guides/jwt-cookies/)
 - [Social Authentication](https://dj-rest-auth.readthedocs.io/en/latest/guides/social-auth/)
+- [MFA Guide](https://dj-rest-auth.readthedocs.io/en/latest/guides/mfa/)
 
 ## Contributing
 

demo/.dockerignore

@@ -0,0 +1,46 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+backend/db.sqlite3
+
+# Virtual Environment
+venv/
+.venv/
+.env
+
+# Node
+node_modules/
+npm-debug.log
+yarn-error.log
+.next/
+
+# IDEs
+.idea/
+.vscode/
+
+# Project Specific
+spa-client/node_modules/
+spa-client/.next/

demo/README.md

@@ -0,0 +1,56 @@
+# dj-rest-auth Demo Architecture
+
+This directory contains a complete demonstration of a modern Single Page Application (SPA) authentication flow using `dj-rest-auth`.
+
+## Overview
+
+The demo consists of two main components:
+
+1.  **Backend (`demo/backend`)**: A Django project using `dj-rest-auth`, `django-allauth`, and `djangorestframework-simplejwt`. It exposes REST APIs for registration, login, and Multi-Factor Authentication (MFA).
+2.  **Frontend (`demo/spa-client`)**: A Next.js application that consumes the backend APIs. It demonstrates a complete user flow including registration, login, MFA setup (QR code), and MFA verification.
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    User[User / Browser]
+    subgraph Frontend [Next.js App (Port 3000)]
+        Pages[Pages]
+        AuthContext[Auth Context]
+        ApiClient[Axios Client]
+    end
+    subgraph Backend [Django API (Port 8000)]
+        DjRestAuth[dj-rest-auth]
+        AllAuth[django-allauth]
+        MFA[MFA App]
+        DB[(SQLite DB)]
+    end
+
+    User -->|Interacts| Pages
+    Pages -->|Uses| AuthContext
+    AuthContext -->|Requests| ApiClient
+    ApiClient -->|HTTP Requests| DjRestAuth
+    
+    DjRestAuth -->|Auth Logic| AllAuth
+    DjRestAuth -->|MFA Logic| MFA
+    AllAuth -->|Persists| DB
+    MFA -->|Persists| DB
+
+    note1[Login Flow]
+    User -.->|1. Credentials| Pages
+    Pages -.->|2. Login| DjRestAuth
+    DjRestAuth -.->|3. MFA Required + Ephemeral Token| Pages
+    Pages -.->|4. Verify Code + Token| DjRestAuth
+    DjRestAuth -.->|5. Auth Token / Session| User
+```
+
+## Running the Demo
+
+The easiest way to run the demo is with Docker Compose:
+
+```bash
+cd demo
+docker-compose up --build
+```
+- Frontend: [http://localhost:3000](http://localhost:3000)
+- Backend: [http://localhost:8000](http://localhost:8000)

demo/backend/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy local package and demo backend
+# Context is expected to be the project root
+COPY . /app/source
+
+# Install the local package and backend requirements
+WORKDIR /app/source/demo/backend
+RUN pip install -r requirements.txt
+
+# Run the server
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

demo/demo/__init__.py demo/backend/demo/__init__.pydemo/demo/__init__.py renamed to demo/backend/demo/__init__.py

@@ -22,7 +22,7 @@
 # SECURITY WARNING: don't run with debug turned on in production!
 DEBUG = True
 
-ALLOWED_HOSTS = []
+ALLOWED_HOSTS = ['*']
 
 # Application definition
 
@@ -39,7 +39,9 @@
     'dj_rest_auth',
     'allauth',
     'allauth.account',
+    'allauth.mfa',
     'dj_rest_auth.registration',
+    'dj_rest_auth.mfa',
     'allauth.socialaccount',
     'allauth.socialaccount.providers.facebook',
     'drf_yasg',
@@ -111,10 +113,8 @@
 ]
 
 REST_AUTH = {
-    'SESSION_LOGIN': True,
-    'USE_JWT': True,
-    'JWT_AUTH_COOKIE': 'auth',
-    'JWT_AUTH_HTTPONLY': False,
+    'SESSION_LOGIN': False,
+    'USE_JWT': False,
 }
 
 EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
@@ -126,9 +126,7 @@
 
 REST_FRAMEWORK = {
     'DEFAULT_AUTHENTICATION_CLASSES': (
-        'rest_framework.authentication.SessionAuthentication',
         'rest_framework.authentication.TokenAuthentication',
-        'dj_rest_auth.jwt_auth.JWTCookieAuthentication'
     ),
     'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
 }
@@ -139,7 +137,15 @@
 }
 
 
-# For demo purposes only. Use a white list in the real world.
-CORS_ORIGIN_ALLOW_ALL = True
+# CORS Configuration
+CORS_ALLOWED_ORIGINS = [
+    "http://localhost:3000",
+    "http://127.0.0.1:3000",
+]
+CORS_ALLOW_CREDENTIALS = True
+CSRF_TRUSTED_ORIGINS = [
+    "http://localhost:3000",
+    "http://127.0.0.1:3000",
+]
 
 DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'

demo/demo/settings.py demo/backend/demo/settings.pydemo/demo/settings.py renamed to demo/backend/demo/settings.py

@@ -1,6 +1,7 @@
 from django.urls import include, re_path
 from django.contrib import admin
 from django.views.generic import RedirectView, TemplateView
+from dj_rest_auth.mfa.views import MFALoginView
 from drf_yasg.views import get_schema_view
 from drf_yasg import openapi
 
@@ -45,8 +46,10 @@
         TemplateView.as_view(template_name="password_reset_confirm.html"),
         name='password_reset_confirm'),
 
+    re_path(r'^dj-rest-auth/login/$', MFALoginView.as_view(), name='rest_login'),
     re_path(r'^dj-rest-auth/', include('dj_rest_auth.urls')),
     re_path(r'^dj-rest-auth/registration/', include('dj_rest_auth.registration.urls')),
+    re_path(r'^dj-rest-auth/', include('dj_rest_auth.mfa.urls')),
     re_path(r'^account/', include('allauth.urls')),
     re_path(r'^admin/', admin.site.urls),
     re_path(r'^accounts/profile/$', RedirectView.as_view(url='/', permanent=True), name='profile-redirect'),

demo/demo/urls.py demo/backend/demo/urls.pydemo/demo/urls.py renamed to demo/backend/demo/urls.py

@@ -0,0 +1,11 @@
+django==5.2.10
+djangorestframework==3.16.1
+djangorestframework-simplejwt==5.5.1
+django-allauth[socialaccount,mfa]==65.14.3
+drf-yasg==1.21.7
+django-cors-headers==4.4.0
+coreapi==2.3.3
+setuptools==78.1.1
+qrcode==8.2
+pyotp==2.9.0
+../../