Updates Docs + Linting Errors

Author: iMerica

README.md

@@ -45,6 +45,64 @@ REST_AUTH = {
 }
 ```
 
+## Multi-Factor Authentication (MFA)
+
+dj-rest-auth supports TOTP-based Multi-Factor Authentication with recovery codes.
+
+### Quick MFA Setup
+
+1. Add `dj_rest_auth.mfa` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = (
+    ...,
+    'dj_rest_auth',
+    'dj_rest_auth.mfa',
+)
+```
+
+2. Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+3. Include MFA URLs and use the MFA-enabled login view:
+
+```python
+from dj_rest_auth.mfa.views import MFALoginView
+
+urlpatterns = [
+    path('dj-rest-auth/login/', MFALoginView.as_view(), name='rest_login'),
+    path('dj-rest-auth/', include('dj_rest_auth.urls')),
+    path('dj-rest-auth/', include('dj_rest_auth.mfa.urls')),
+]
+```
+
+4. (Optional) Install `qrcode` for QR code generation:
+
+```bash
+pip install qrcode[pil]
+```
+
+### MFA Login Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant LoginEndpoint
+    participant MFAVerify
+    
+    Client->>LoginEndpoint: POST username + password
+    LoginEndpoint-->>Client: ephemeral_token + mfa_required: true
+    Client->>MFAVerify: POST ephemeral_token + TOTP code
+    MFAVerify-->>Client: auth_token (JWT or session)
+```
+
+When MFA is enabled for a user, the login endpoint returns an `ephemeral_token` instead of completing authentication. The client must then exchange this token along with a valid TOTP code (or recovery code) at the `/mfa/verify/` endpoint to receive the actual authentication token.
+
+For full MFA documentation, see: https://dj-rest-auth.readthedocs.io/en/latest/mfa.html
+
 ### Testing
 
 Install required modules with `pip install -r  dj_rest_auth/tests/requirements.txt`

dj_rest_auth/mfa/migrations/0001_initial.py

@@ -17,12 +17,22 @@ class Migration(migrations.Migration):
         migrations.CreateModel(
             name='Authenticator',
             fields=[
-                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
-                ('type', models.CharField(choices=[('totp', 'TOTP'), ('recovery_codes', 'Recovery codes')], max_length=20)),
+                ('id', models.BigAutoField(
+                    auto_created=True, primary_key=True,
+                    serialize=False, verbose_name='ID',
+                )),
+                ('type', models.CharField(
+                    choices=[('totp', 'TOTP'), ('recovery_codes', 'Recovery codes')],
+                    max_length=20,
+                )),
                 ('data', models.JSONField(default=dict)),
                 ('created_at', models.DateTimeField(auto_now_add=True)),
                 ('last_used_at', models.DateTimeField(blank=True, null=True)),
-                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='mfa_authenticators', to=settings.AUTH_USER_MODEL)),
+                ('user', models.ForeignKey(
+                    on_delete=django.db.models.deletion.CASCADE,
+                    related_name='mfa_authenticators',
+                    to=settings.AUTH_USER_MODEL,
+                )),
             ],
             options={
                 'unique_together': {('user', 'type')},

dj_rest_auth/mfa/recovery_codes.py

@@ -3,7 +3,6 @@
 import os
 
 from django.utils import timezone
-from django.utils.translation import gettext_lazy as _
 
 from dj_rest_auth.app_settings import api_settings
 

dj_rest_auth/mfa/totp.py

@@ -1,6 +1,5 @@
 import pyotp
 from django.utils import timezone
-from django.utils.translation import gettext_lazy as _
 
 from dj_rest_auth.app_settings import api_settings
 

dj_rest_auth/mfa/urls.py

@@ -15,5 +15,9 @@
     re_path(r'^mfa/totp/deactivate/?$', TOTPDeactivateView.as_view(), name='mfa_totp_deactivate'),
     re_path(r'^mfa/status/?$', MFAStatusView.as_view(), name='mfa_status'),
     re_path(r'^mfa/recovery-codes/?$', RecoveryCodesView.as_view(), name='mfa_recovery_codes'),
-    re_path(r'^mfa/recovery-codes/regenerate/?$', RecoveryCodesRegenerateView.as_view(), name='mfa_recovery_codes_regenerate'),
+    re_path(
+        r'^mfa/recovery-codes/regenerate/?$',
+        RecoveryCodesRegenerateView.as_view(),
+        name='mfa_recovery_codes_regenerate',
+    ),
 ]

dj_rest_auth/mfa/utils.py

@@ -1,5 +1,5 @@
 from django.contrib.auth import get_user_model
-from django.core.signing import BadSignature, SignatureExpired, TimestampSigner
+from django.core.signing import TimestampSigner
 
 from dj_rest_auth.app_settings import api_settings
 

dj_rest_auth/tests/test_mfa.py

@@ -2,7 +2,6 @@
 from django.contrib.auth import get_user_model
 from django.test import TestCase, override_settings, modify_settings
 
-from dj_rest_auth.mfa.models import Authenticator
 from dj_rest_auth.mfa.totp import TOTP, generate_totp_secret, validate_totp_code
 from dj_rest_auth.mfa.recovery_codes import RecoveryCodes
 from dj_rest_auth.mfa.utils import create_ephemeral_token, verify_ephemeral_token, is_mfa_enabled
@@ -223,7 +222,7 @@ def test_mfa_verify_invalid_code(self):
 
     def test_mfa_verify_invalid_token(self):
         """Verify MFA with invalid ephemeral token should fail."""
-        response = self.post(
+        self.post(
             self.mfa_verify_url,
             data={'ephemeral_token': 'invalid-token', 'code': '123456'},
             status_code=400,
@@ -277,7 +276,7 @@ def test_totp_deactivate(self):
 
         totp = pyotp.TOTP(secret)
         code = totp.now()
-        response = self.post(
+        self.post(
             self.totp_deactivate_url,
             data={'code': code},
             status_code=200,
@@ -290,7 +289,7 @@ def test_totp_deactivate_invalid_code(self):
         TOTP.activate(self.user, secret)
         self._mfa_login_get_token(secret)
 
-        response = self.post(
+        self.post(
             self.totp_deactivate_url,
             data={'code': '000000'},
             status_code=400,
@@ -321,7 +320,7 @@ def test_recovery_codes_regenerate(self):
     def test_recovery_codes_regenerate_without_mfa(self):
         """Should fail to regenerate when MFA is not enabled."""
         self._login_get_token()
-        response = self.post(self.recovery_codes_regenerate_url, status_code=400)
+        self.post(self.recovery_codes_regenerate_url, status_code=400)
 
     def test_full_mfa_flow(self):
         """End-to-end: activate MFA, login with TOTP, login with recovery code,

docs/configuration.rst

@@ -251,3 +251,90 @@ views when using the JWT cookie for auth. It does not effect a client's ability
 to authenticate using a JWT Bearer Auth header without a CSRF token (though
 getting the JWT token in the first place without passing a CSRF token isnt
 possible). Default is ``False``.
+
+
+MFA Settings
+============
+
+The following settings configure Multi-Factor Authentication behavior. These are
+only relevant when ``dj_rest_auth.mfa`` is included in ``INSTALLED_APPS``.
+
+.. note:: For complete MFA documentation, see :doc:`MFA (Multi-Factor Auth) </mfa>`.
+
+``MFA_EPHEMERAL_TOKEN_TIMEOUT``
+===============================
+
+Time in seconds before the ephemeral token (returned during MFA login flow) expires.
+After this timeout, the user must re-authenticate with username/password.
+Default is ``300`` (5 minutes).
+
+``MFA_TOTP_DIGITS``
+===================
+
+Number of digits in the TOTP code. Most authenticator apps use 6 digits.
+Default is ``6``.
+
+``MFA_TOTP_PERIOD``
+===================
+
+Time period in seconds for TOTP code validity. This determines how often a new
+code is generated. Standard value is 30 seconds. Default is ``30``.
+
+``MFA_TOTP_ISSUER``
+===================
+
+Issuer name displayed in authenticator apps. This helps users identify which
+account the TOTP is for. Default is ``''`` (empty string).
+
+Example:
+
+.. code-block:: python
+
+    REST_AUTH = {
+        'MFA_TOTP_ISSUER': 'MyApp',
+    }
+
+``MFA_RECOVERY_CODE_COUNT``
+===========================
+
+Number of recovery codes to generate when MFA is activated. Recovery codes
+provide backup access if the authenticator device is lost. Default is ``10``.
+
+``MFA_VERIFY_SERIALIZER``
+=========================
+
+The path to the serializer class for MFA verification (exchanging ephemeral token
++ TOTP code for auth token). Default is
+``'dj_rest_auth.mfa.serializers.MFAVerifySerializer'``.
+
+``MFA_TOTP_ACTIVATE_INIT_SERIALIZER``
+=====================================
+
+The path to the serializer class for the TOTP activation initialization response
+(GET request to generate secret). Default is
+``'dj_rest_auth.mfa.serializers.TOTPActivateInitSerializer'``.
+
+``MFA_TOTP_ACTIVATE_CONFIRM_SERIALIZER``
+========================================
+
+The path to the serializer class for confirming TOTP activation (POST request
+with secret and code). Default is
+``'dj_rest_auth.mfa.serializers.TOTPActivateConfirmSerializer'``.
+
+``MFA_TOTP_DEACTIVATE_SERIALIZER``
+==================================
+
+The path to the serializer class for TOTP deactivation. Default is
+``'dj_rest_auth.mfa.serializers.TOTPDeactivateSerializer'``.
+
+``MFA_STATUS_SERIALIZER``
+=========================
+
+The path to the serializer class for the MFA status response. Default is
+``'dj_rest_auth.mfa.serializers.MFAStatusSerializer'``.
+
+``MFA_RECOVERY_CODES_SERIALIZER``
+=================================
+
+The path to the serializer class for recovery codes responses. Default is
+``'dj_rest_auth.mfa.serializers.RecoveryCodesSerializer'``.

docs/index.rst

@@ -20,6 +20,7 @@ Contents
    Installation <installation>
    API endpoints <api_endpoints>
    Configuration <configuration>
+   MFA (Multi-Factor Auth) <mfa>
    Demo project <demo>
    FAQ <faq>
    Disclosure Policy <disclosure>