CSRF Prevention: Cross-Site Request Forgery Defense Guide

TL;DR

• Bottom line: Combine CSRF tokens (synchronizer or signed double-submit cookie pattern) with SameSite cookie attributes and Fetch Metadata header validation for layered CSRF defense -- no single technique is sufficient alone.
• Key tool/command: {% csrf_token %} (Django), csrf-csrf middleware (Express), http.csrf(Customizer.withDefaults()) (Spring Security) -- use your framework's built-in CSRF protection.
• Watch out for: XSS vulnerabilities defeat ALL CSRF protections -- an attacker who can inject scripts can read and submit tokens.
• Works with: All major web frameworks have built-in CSRF support. SameSite cookies supported in all modern browsers (Chrome 51+, Firefox 60+, Safari 12+, Edge 16+). Fetch Metadata supported since March 2023.

Constraints

• NEVER use GET requests for state-changing operations -- CSRF tokens cannot protect GET endpoints
• XSS defeats ALL CSRF defenses -- fix XSS first before relying on CSRF tokens
• SameSite cookies are defense-in-depth, NOT a standalone CSRF solution
• CSRF tokens MUST be compared using constant-time comparison to prevent timing attacks
• NEVER transmit CSRF tokens in URL query strings -- they leak via Referer headers and server logs
• The deprecated csurf npm package has known bypasses -- use csrf-csrf or framework-native protection instead

Quick Reference

Attack Vectors & Defenses

Prevention Methods Comparison

Decision Tree

START: What type of state-changing requests does your app make?
├── HTML form submissions (POST)?
│   ├── YES → Use Synchronizer Token Pattern (hidden field + server session)
│   │         Django: {% csrf_token %}, Spring: _csrf.token, Rails: authenticity_token
│   └── NO ↓
├── AJAX/fetch only (SPA architecture)?
│   ├── YES → Require custom header (X-CSRF-Token) or use application/json Content-Type
│   │         + signed double-submit cookie for stateless validation
│   └── NO ↓
├── Both forms and AJAX?
│   ├── YES → Synchronizer token for forms + custom header with same token for AJAX
│   └── NO ↓
├── Stateless API with JWT (no session cookies)?
│   ├── YES → CSRF protection not needed (no cookies = no CSRF risk)
│   └── NO ↓
├── Microservices behind API gateway?
│   ├── YES → Validate Fetch Metadata (Sec-Fetch-Site) at gateway level
│   └── NO ↓
└── DEFAULT → Synchronizer Token Pattern + SameSite=Lax cookies + Fetch Metadata

Step-by-Step Guide

1. Set SameSite attribute on all session cookies

SameSite prevents the browser from sending cookies with cross-site requests. Set it to Strict where possible, Lax as minimum. [src1]

Set-Cookie: sessionid=abc123; SameSite=Lax; Secure; HttpOnly; Path=/
Set-Cookie: __Host-sessionid=abc123; SameSite=Strict; Secure; HttpOnly; Path=/

Verify: Browser DevTools > Application > Cookies -- confirm SameSite attribute is set. Test cross-site form submission -- cookie should NOT be sent with POST.

2. Implement framework-native CSRF token protection

Use your framework's built-in CSRF middleware rather than building your own. [src6]

# Django settings.py -- enabled by default
MIDDLEWARE = [
    'django.middleware.csrf.CsrfViewMiddleware',
]
# Templates: <form method="post">{% csrf_token %} ... </form>

Verify: Submit a form without the CSRF token -- should receive 403 Forbidden.

3. Add Fetch Metadata validation middleware

Fetch Metadata headers let you reject cross-site requests at the server level before any application logic runs. [src7]

function fetchMetadataPolicy(req, res, next) {
  const site = req.headers['sec-fetch-site'];
  if (!site) return next();
  if (['same-origin', 'same-site', 'none'].includes(site)) return next();
  if (req.headers['sec-fetch-mode'] === 'navigate'
      && req.method === 'GET') return next();
  res.status(403).json({ error: 'Cross-site request blocked' });
}
app.use(fetchMetadataPolicy);

Verify: Send a cross-origin POST from a different domain -- should receive 403.

4. Validate Origin and Referer headers

Check that the Origin (or Referer) header matches your expected domain on state-changing requests. [src1]

ALLOWED_ORIGINS = {'https://example.com', 'https://www.example.com'}

def validate_origin(request):
    origin = request.headers.get('Origin')
    if origin and origin not in ALLOWED_ORIGINS:
        return False
    return True

Verify: Set Origin header to https://evil.com in a request tool -- should be rejected.

5. Protect login and unauthenticated forms

Login forms are vulnerable to CSRF (login CSRF) even without an active session. Use a pre-session token. [src1]

from django.views.decorators.csrf import csrf_protect

@csrf_protect
def login_view(request):
    if request.method == 'POST':
        # CsrfViewMiddleware validates token before session exists
        pass

Verify: Submit the login form without csrfmiddlewaretoken -- should return 403.

Code Examples

Python/Django: Complete CSRF Protection

# settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
]
CSRF_COOKIE_SAMESITE = 'Strict'
CSRF_COOKIE_SECURE = True
CSRF_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = 'Strict'
SESSION_COOKIE_SECURE = True

# views.py
from django.shortcuts import render

def transfer(request):
    if request.method == 'POST':
        # Token validated by CsrfViewMiddleware
        amount = request.POST['amount']
        recipient = request.POST['recipient']
    return render(request, 'transfer.html')

# For AJAX: read token from cookie or hidden field
# fetch('/api/transfer', {
#   method: 'POST',
#   headers: { 'X-CSRFToken': csrfToken },
#   body: JSON.stringify({ amount: 100 })
# });

Node.js/Express: Signed Double-Submit Cookie

const express = require('express');            // ^4.18.0
const { doubleCsrf } = require('csrf-csrf');   // ^3.0.0
const cookieParser = require('cookie-parser'); // ^1.4.0
const app = express();
app.use(cookieParser());
app.use(express.urlencoded({ extended: true }));

const { doubleCsrfProtection, generateToken } = doubleCsrf({
  getSecret: () => process.env.CSRF_SECRET,
  cookieName: '__Host-csrf',
  cookieOptions: {
    sameSite: 'strict', secure: true,
    httpOnly: true, path: '/'
  },
  getTokenFromRequest: (req) =>
    req.headers['x-csrf-token'] || req.body._csrf
});
app.use(doubleCsrfProtection);

app.get('/form', (req, res) => {
  const token = generateToken(req, res);
  res.send(`<form method="POST" action="/transfer">
    <input type="hidden" name="_csrf" value="${token}">
    <button type="submit">Transfer</button>
  </form>`);
});

Java/Spring Boot: Built-in CSRF with Thymeleaf

// SecurityConfig.java -- Spring Security 6.x
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.csrf(csrf -> csrf
        .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
    );
    return http.build();
}
// Thymeleaf auto-injects hidden _csrf field in th:action forms
// For AJAX: read token from meta tag, set in X-CSRF-TOKEN header

// For stateless JWT APIs (no session cookies):
// http.csrf(csrf -> csrf.disable())
//   .sessionManagement(sm ->
//     sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS));

Anti-Patterns

Wrong: Using GET for state-changing operations

<!-- BAD -- GET requests are not protected by CSRF tokens -->
<a href="/api/delete-account?confirm=true">Delete Account</a>
<!-- Attacker embeds: <img src="/api/delete-account?confirm=true"> -->

Correct: Use POST with CSRF token for state changes

<!-- GOOD -- POST with CSRF token -->
<form method="POST" action="/api/delete-account">
  <input type="hidden" name="csrf_token" value="{{csrf_token}}">
  <button type="submit">Delete Account</button>
</form>

Wrong: Naive double-submit cookie without HMAC signing

// BAD -- unsigned double-submit cookie vulnerable to cookie tossing
const token = crypto.randomBytes(32).toString('hex');
res.cookie('csrf', token);
// Attacker on subdomain sets their own csrf cookie + matching value

Correct: Signed double-submit cookie with HMAC

// GOOD -- HMAC-signed token bound to session
const crypto = require('crypto');
function generateCsrfToken(sessionId, secret) {
  const random = crypto.randomBytes(16).toString('hex');
  const hmac = crypto.createHmac('sha256', secret)
    .update(sessionId + random).digest('hex');
  return hmac + '.' + random;
}
function validateCsrfToken(token, sessionId, secret) {
  const [hmac, random] = token.split('.');
  const expected = crypto.createHmac('sha256', secret)
    .update(sessionId + random).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(expected));
}

Wrong: Disabling CSRF protection for convenience

// BAD -- disabling CSRF on session-based app
http.csrf(csrf -> csrf.disable());
// "It works now!" -- and so do CSRF attacks

Correct: Disable only for stateless JWT APIs

// GOOD -- disable CSRF only when session cookies are not used
http
  .csrf(csrf -> csrf.disable())
  .sessionManagement(sm ->
    sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
  .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
// No session cookie = no CSRF risk

Wrong: Using the deprecated csurf package

// BAD -- csurf deprecated (Sep 2022) with known bypasses
const csurf = require('csurf');  // DO NOT USE
app.use(csurf());

Correct: Use csrf-csrf or framework-native protection

// GOOD -- csrf-csrf implements signed double-submit cookie
const { doubleCsrf } = require('csrf-csrf');  // ^3.0.0
const { doubleCsrfProtection } = doubleCsrf({
  getSecret: () => process.env.CSRF_SECRET,
  cookieName: '__Host-csrf',
  cookieOptions: { sameSite: 'strict', secure: true, httpOnly: true }
});
app.use(doubleCsrfProtection);

Common Pitfalls

• SameSite=Lax allows GET requests: Lax only blocks cross-site POST/PUT/DELETE. If your app changes state via GET, SameSite=Lax provides no protection. Fix: Never use GET for state changes. [src1]
• CSRF token in cookie only: Placing the token only in a cookie (not also in a form field or header) provides zero protection -- browsers auto-send cookies. Fix: Token must appear in both a cookie AND a request body/header. [src2]
• Missing CSRF on login forms: Login CSRF allows an attacker to log the victim into the attacker's account. Fix: Apply CSRF protection to login and other pre-authentication forms. [src1]
• XSS negates CSRF protection: An XSS vulnerability lets the attacker read CSRF tokens from the DOM and submit forged requests. Fix: Prevent XSS first. [src4]
• Cross-origin same-site attacks: SameSite cookies protect against cross-site but NOT cross-origin same-site requests. Fix: Use CSRF tokens + __Host- cookie prefix. [src2]
• Referer stripping breaks validation: Privacy extensions strip the Referer header, causing false rejections. Fix: Use Origin header as primary check; fall back to Referer. [src1]
• BREACH attack on CSRF tokens: Compression + encryption can leak CSRF token bytes. Fix: Use per-request token masking (Django and Spring do this automatically). [src5]

Diagnostic Commands

# Check SameSite attribute on cookies
curl -sI -b cookies.txt https://your-site.com/login | grep -i set-cookie

# Test CSRF protection -- submit without token (should fail)
curl -X POST https://your-site.com/api/transfer \
  -H "Cookie: sessionid=valid_session" \
  -d "amount=100&recipient=attacker"
# Expected: 403 Forbidden

# Verify Origin header validation
curl -X POST https://your-site.com/api/transfer \
  -H "Origin: https://evil.com" \
  -H "Cookie: sessionid=valid_session" \
  -d "amount=100"
# Expected: 403 Forbidden

# Scan for CSRF vulnerabilities with OWASP ZAP
docker run -t ghcr.io/zaproxy/zaproxy:stable zap-baseline.py \
  -t https://your-site.com -r report.html

# Find forms missing CSRF tokens
grep -rn '<form' --include="*.html" . | grep -v 'csrf\|_token'

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• XSS is a strictly more powerful attack than CSRF -- if an attacker has XSS, they can bypass all CSRF defenses by reading tokens from the DOM
• SameSite=Lax is now the browser default, which blocks most naive CSRF attacks, but sophisticated attackers can still exploit same-site cross-origin scenarios
• Mobile apps using WebView may not enforce SameSite cookies consistently -- test CSRF protection specifically in your mobile WebView environment
• Fetch Metadata headers are not sent to non-HTTPS URLs -- your site must use HTTPS for this defense to work
• Some CDNs and reverse proxies may strip Sec-Fetch-* headers -- verify they are forwarded to your application
• CSRF protection must be applied to ALL state-changing endpoints, including file uploads, settings changes, and API endpoints -- not just financial transactions