Agent skill

csrf-auth-debugger

Debug CSRF token issues and authentication problems including 403 Forbidden errors, cookie issues, JWT tokens, OAuth flows, and session management. Use when troubleshooting CSRF verification failed, 403 errors on POST requests, login not working, or token refresh issues.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/csrf-auth-debugger-allthriveai-allthriveai

SKILL.md

CSRF & Authentication Debugger

Analyzes and debugs CSRF and authentication issues in this project.

Project Context

  • Authentication: JWT tokens in httpOnly cookies + OAuth (Google, GitHub)
  • CSRF: Django's CSRF middleware with cookie-based tokens
  • OAuth library: django-allauth
  • Token service: services/auth/tokens.py
  • Frontend API: Axios with credentials and CSRF interceptor

Authentication Architecture

Browser
    ↓ Request with cookies
    │ - access_token (httpOnly, JWT)
    │ - refresh_token (httpOnly, JWT)
    │ - csrftoken (readable by JS)
Django
    ↓ CsrfViewMiddleware
    ↓ JWTAuthenticationMiddleware
    ↓ View/API endpoint

When to Use

  • "CSRF verification failed"
  • "403 Forbidden on POST/PUT/DELETE"
  • "Login not working"
  • "Token expired"
  • "OAuth callback failing"
  • "Cookies not being set"
  • "X-CSRFToken header missing"

CSRF Flow

How CSRF Works in This Project

  1. GET /api/v1/auth/csrf/ - Sets csrftoken cookie
  2. Frontend reads cookie - getCookie('csrftoken')
  3. POST/PUT/DELETE requests - Include X-CSRFToken header
  4. Django validates - Compares header to cookie

Frontend CSRF Handling

typescript
// frontend/src/services/api.ts
api.interceptors.request.use((config) => {
  if (['post', 'put', 'patch', 'delete'].includes(method)) {
    const csrfToken = getCookie('csrftoken');
    if (csrfToken) {
      config.headers['X-CSRFToken'] = csrfToken;
    }
  }
});

Common CSRF Issues

403 "CSRF verification failed":

  1. Missing CSRF cookie

    bash
    # Check if cookie exists in browser DevTools > Application > Cookies
# Should see: csrftoken

  2. Missing X-CSRFToken header

    javascript
    // Check Network tab - request headers should include:
// X-CSRFToken: <token value>

  3. Cookie not sent (CORS)

    typescript
    // Axios must have:
withCredentials: true

  4. Domain mismatch

    python
    # settings.py - check these match your domain
CSRF_COOKIE_DOMAIN = None  # or '.yourdomain.com'
CSRF_TRUSTED_ORIGINS = ['http://localhost:3000', ...]

  5. SameSite cookie issues

    python
    # For cross-origin requests:
CSRF_COOKIE_SAMESITE = 'Lax'  # or 'None' with Secure

Common Auth Issues

JWT token expired:

python
# Check token expiry in services/auth/tokens.py
ACCESS_TOKEN_LIFETIME = timedelta(minutes=15)
REFRESH_TOKEN_LIFETIME = timedelta(days=7)

Cookies not set after login:

python
# Check response has Set-Cookie headers
# Verify SameSite and Secure flags match environment

OAuth callback failing:

bash
# Check callback URL matches exactly:
# - In Google/GitHub OAuth app settings
# - In django-allauth config
# - Including trailing slashes!

Debugging Steps

1. Check CSRF Cookie Exists

javascript
// Browser console
document.cookie.split(';').find(c => c.includes('csrftoken'))

2. Check Request Headers

Network tab > Request > Headers
Look for: X-CSRFToken: <value>

3. Check Django Logs

bash
docker compose logs web | grep -i csrf

4. Test CSRF Endpoint

bash
curl -c cookies.txt http://localhost:8000/api/v1/auth/csrf/
cat cookies.txt  # Should show csrftoken

5. Verify Settings

python
# Django shell
from django.conf import settings
print(settings.CSRF_COOKIE_NAME)
print(settings.CSRF_TRUSTED_ORIGINS)
print(settings.CORS_ALLOWED_ORIGINS)

Key Files to Check

Backend:
├── config/settings.py          # CSRF_*, CORS_*, cookie settings
├── core/auth/views.py          # Login, logout, OAuth views
├── core/views/core_views.py    # CSRF token endpoint
├── services/auth/tokens.py     # JWT token creation
└── services/auth/__init__.py   # set_auth_cookies function

Frontend:
├── src/services/api.ts         # Axios CSRF interceptor
├── src/contexts/AuthContext.tsx # Auth state management
└── src/pages/AuthPage.tsx      # Login/OAuth UI

Django CSRF Settings

python
# config/settings.py - key settings
CSRF_COOKIE_NAME = 'csrftoken'
CSRF_HEADER_NAME = 'HTTP_X_CSRFTOKEN'
CSRF_COOKIE_HTTPONLY = False  # Must be False for JS to read
CSRF_COOKIE_SAMESITE = 'Lax'
CSRF_TRUSTED_ORIGINS = [
    'http://localhost:3000',
    'http://localhost:8000',
]

Views Exempt from CSRF

Some views use @csrf_exempt (check if issue is with exempt view):

bash
grep -r "csrf_exempt" core/

Testing Authentication

bash
# Login and get tokens
curl -X POST http://localhost:8000/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"test@example.com","password":"password"}'

# Use tokens for authenticated request
curl http://localhost:8000/api/v1/users/me/ \
  -b cookies.txt

Didn't find tool you were looking for?

Be as detailed as possible for better results