RobustAuth

Modern session-based opaque token authentication for Django REST Framework.

RobustAuth replaces JWT complexity with secure, database-backed opaque tokens — giving you instant revocation, full session intelligence, and production-grade security controls out of the box.

Why RobustAuth?

Installation

pip install robustauth

# Optional: device/browser detection
pip install robustauth[device]

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "robustauth",
]

Run migrations:

python manage.py migrate

Add URL patterns:

# urls.py
from django.urls import path, include

urlpatterns = [
    path("auth/", include("robustauth.urls")),
    ...
]

Quick Start

1. Configure (optional — sensible defaults apply)

# settings.py
ROBUST_AUTH = {
    "ACCESS_TOKEN_TTL": 900,          # 15 min
    "REFRESH_TOKEN_TTL": 604800,      # 7 days
    "SESSION_POLICY": "single",       # one device at a time
    "ROTATE_REFRESH_TOKENS": True,
    "REVOKE_ON_PASSWORD_CHANGE": True,
    "TRACK_IPS": True,
    "TRACK_USER_AGENTS": True,
    "MAX_SESSIONS": 3,                # used when SESSION_POLICY = "max_count"
}

2. Set authentication on your views

# settings.py
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "robustauth.authentication.RobustTokenAuthentication",
    ],
}

Or per-view:

from robustauth.authentication import RobustTokenAuthentication

class MyView(APIView):
    authentication_classes = [RobustTokenAuthentication]
    permission_classes = [IsAuthenticated]

API Endpoints

All endpoints are prefixed with wherever you mounted robustauth.urls.

POST /auth/login/

Authenticate a user and receive token pair.

Request:

{
  "username": "alice",
  "password": "secret"
}

Response 200:

{
  "access_token": "a3f9...",
  "refresh_token": "b7c2...",
  "session_id": "550e8400-e29b-...",
  "token_type": "Bearer"
}

POST /auth/token/refresh/

Exchange a refresh token for a new token pair. The old refresh token is invalidated.

Request:

{ "refresh_token": "b7c2..." }

Response 200:

{
  "access_token": "d1e4...",
  "refresh_token": "f5a8...",
  "token_type": "Bearer"
}

POST /auth/logout/

Revoke the current session. Requires Authorization: Bearer <access_token>.

Response 200:

{ "detail": "Logged out successfully." }

POST /auth/logout/all/

Revoke all sessions (optionally keep the current one alive).

Request:

{ "keep_current": true }

GET /auth/sessions/

List all active sessions for the authenticated user.

Response:

[
  {
    "id": "550e8400-...",
    "state": "active",
    "ip_address": "41.58.12.34",
    "device_type": "mobile",
    "os_family": "Android",
    "browser_family": "Chrome Mobile",
    "device_name": "Samsung SM-G991",
    "created_at": "2024-01-15T10:23:00Z",
    "last_activity": "2024-01-15T14:05:00Z",
    "is_current": true
  }
]

DELETE /auth/sessions/<uuid>/

Revoke a specific session by ID.

GET /auth/history/

Return the authentication event log for the authenticated user.

Query params: ?limit=50

Response:

[
  {
    "id": 1,
    "event": "login_success",
    "ip_address": "41.58.12.34",
    "user_agent": "Mozilla/5.0 ...",
    "extra": {},
    "timestamp": "2024-01-15T10:23:00Z"
  },
  ...
]

Session Policies

Control concurrent login behaviour via SESSION_POLICY:

ROBUST_AUTH = {
    "SESSION_POLICY": "max_count",
    "MAX_SESSIONS": 3,
    "REVOKE_OLDEST_ON_LIMIT": True,   # False → raise error instead
}

Signals

Hook into authentication events in your own apps:

from robustauth import signals
from django.dispatch import receiver

@receiver(signals.token_reuse_detected)
def alert_security(sender, user, session, ip_address, **kwargs):
    # Send email, create alert, block IP, etc.
    SecurityAlert.objects.create(user=user, ip=ip_address)

@receiver(signals.brute_force_threshold_hit)
def handle_brute_force(sender, username, ip_address, failure_count, **kwargs):
    BlockedIP.objects.get_or_create(ip=ip_address)

@receiver(signals.user_logged_in)
def on_login(sender, user, session, **kwargs):
    send_new_login_email(user, session)

@receiver(signals.session_limit_reached)
def on_limit(sender, user, active_sessions, **kwargs):
    notify_user(user, "You've reached the maximum number of active sessions.")

Available signals:

Password Change Integration

Automatically revoke all other sessions on password change:

from robustauth.session_manager import SessionManager

def change_password_view(request):
    # ... your password change logic ...
    user.set_password(new_password)
    user.save()

    # Revoke all sessions except the current one
    current_session = request.auth.session  # if using RobustTokenAuthentication
    SessionManager.on_password_change(user, current_session=current_session)

Middleware (optional)

Attach request.robust_session to all requests:

MIDDLEWARE = [
    ...
    "robustauth.middleware.RobustAuthMiddleware",
]

Then in any view:

def my_view(request):
    session = request.robust_session  # Session object or None

Cleanup

Remove expired tokens and prune history. Add to your cron or Celery beat:

python manage.py robustauth_cleanup

# Preview without deleting
python manage.py robustauth_cleanup --dry-run

Example Celery beat config:

CELERY_BEAT_SCHEDULE = {
    "robustauth-cleanup": {
        "task": "your_app.tasks.robustauth_cleanup",
        "schedule": crontab(hour=3, minute=0),  # daily at 3am
    }
}

Configuration Reference

Running Tests

pip install -e ".[dev]"
pytest

Changelog

0.1.0

• Initial release
• Opaque token authentication with hashed storage
• Access + refresh token pair with rotation
• Refresh token reuse detection with family revocation
• Session policies: single / multi / max_count
• Device and browser fingerprinting
• Login / logout / failed login history
• Brute-force threshold signal
• Sliding sessions
• Password change revocation
• Django admin integration
• robustauth_cleanup management command

License

MIT — see LICENSE.