CSRF

Backend Fundamentals · Backend Security · 10 min read

1. What problem does this solve?

Motivation
When a user is logged into a web application, the browser automatically sends the session cookie with every request to that domain. A malicious site can trick the user’s browser into sending a request to the target site without the user’s knowledge. If the target site trusts the cookie, it will execute the request as if the user intended it. This is called Cross‑Site Request Forgery (CSRF).

What problem exists?

• A logged‑in user can be coerced into performing unwanted actions (e.g., changing an email address, transferring money, deleting data).
• The attacker does not need to know the user’s credentials; they only need the user’s browser to send a request.

Why the problem matters

• Data integrity: Unauthorized state changes can corrupt data.
• Financial loss: In e‑commerce or banking, CSRF can trigger real money transfers.
• Reputation: Users lose trust if their accounts can be manipulated.

What happens if this concept is not used?

• Any authenticated endpoint that performs state changes (POST, PUT, DELETE) becomes vulnerable.
• Attackers can build automated scripts that exploit the vulnerability at scale.

Where this concept appears in real backend systems

• Traditional web apps with session cookies (Express, Django, Rails).
• Single‑page applications (React, Vue) that rely on cookies for authentication.
• APIs that use cookie‑based auth (not JWT or OAuth bearer tokens).

2. Mental model

Analogy
Imagine you have a key that opens your front door. You leave the key on the kitchen counter. A stranger walks in, sees the key, and uses it to enter your house while you’re away. The key is the session cookie; the stranger’s trick is the malicious site that forces your browser to send a request.

Engineering model

1. Session cookie – automatically attached to every request to the target domain.
2. Same‑origin policy – browsers restrict scripts from other origins from reading the cookie, but they can still send it.
3. CSRF protection – a secret value (token) that the server generates and the client must send back with each state‑changing request. The server verifies the token before acting.

3. Deep explanation

4. How it works

1. User logs in → server creates a session and sets a session cookie (sid) and a CSRF token cookie (_csrf).
2. Client loads a page → JavaScript reads the _csrf cookie.
3. Client submits a form or sends an AJAX request → it includes the CSRF token in a hidden field or X-CSRF-Token header.
4. Server receives request → middleware reads the token from the request and compares it to the token stored in the session or the cookie.
5. If tokens match → request proceeds.
6. If tokens mismatch or missing → server responds with 403 Forbidden.

sequenceDiagram
    participant U as User
    participant B as Browser
    participant S as Server
    U->>B: GET /login
    B->>S: POST /login (credentials)
    S->>B: Set-Cookie: sid=...; HttpOnly
    S->>B: Set-Cookie: _csrf=abc123; SameSite=Lax
    U->>B: GET /dashboard
    B->>S: GET /dashboard; Cookie: sid=...
    S->>B: Render page with hidden input _csrf=abc123
    U->>B: POST /transfer (amount=100)
    B->>S: POST /transfer; Cookie: sid=...; X-CSRF-Token: abc123
    S->>S: Verify token
    S->>B: 200 OK

5. Practical implementation

Below is a minimal Express + TypeScript example using the csurf middleware (synchronizer token pattern). It also shows a double‑submit cookie approach for comparison.

// src/server.ts
import express from 'express';
import cookieParser from 'cookie-parser';
import csrf from 'csurf';

const app = express();
app.use(cookieParser());

// --- Synchronizer token pattern ------------------------------------
const syncCsrfProtection = csrf({
  cookie: { key: '_csrf', httpOnly: true, sameSite: 'lax' },
});

app.get('/form', syncCsrfProtection, (req, res) => {
  // Render a form that includes the CSRF token
  res.send(`
    <form method="POST" action="/submit">
      <input type="hidden" name="_csrf" value="${req.csrfToken()}">
      <input type="text" name="data">
      <button type="submit">Send</button>
    </form>
  `);
});

app.post('/submit', syncCsrfProtection, (req, res) => {
  // CSRF token already validated by middleware
  res.send(`Received: ${req.body.data}`);
});

// --- Double‑submit cookie pattern ----------------------------------
const doubleSubmitCsrf = (req: express.Request, res: express.Response, next: express.NextFunction) => {
  const tokenFromCookie = req.cookies._csrf;
  const tokenFromHeader = req.headers['x-csrf-token'] as string | undefined;

  if (!tokenFromCookie || !tokenFromHeader || tokenFromCookie !== tokenFromHeader) {
    return res.status(403).send('CSRF token missing or invalid');
  }
  next();
};

app.get('/ds-form', (req, res) => {
  // Generate a random token and set it in a cookie
  const token = crypto.randomBytes(32).toString('hex');
  res.cookie('_csrf', token, { httpOnly: false, sameSite: 'lax' }); // accessible to JS
  res.send(`
    <form method="POST" action="/ds-submit">
      <input type="text" name="data">
      <button type="submit">Send</button>
      <script>
        // Attach token to header on submit
        document.querySelector('form').addEventListener('submit', e => {
          e.preventDefault();
          fetch('/ds-submit', {
            method: 'POST',
            headers: { 'X-CSRF-Token': '${token}' },
            body: new FormData(e.target)
          }).then(r => r.text()).then(console.log);
        });
      </script>
    </form>
  `);
});

app.post('/ds-submit', doubleSubmitCsrf, (req, res) => {
  res.send(`Double‑submit received: ${req.body.data}`);
});

app.listen(3000, () => console.log('Server listening on :3000'));

Key lines explained

• csrf({ cookie: { ... } }) – tells csurf to store the token in a cookie instead of the session.
• req.csrfToken() – generates a new token for the current request.
• In the double‑submit example, the token is stored in a cookie that the browser can read (httpOnly: false) and also sent in a custom header. The server verifies both values match.

6. Production considerations

7. Common mistakes

8. Senior engineer perspective

What changes at scale?

• Token distribution: In a microservice architecture, each service must validate CSRF tokens. Centralizing token generation (e.g., a dedicated auth service) avoids duplication.
• Statelessness: Prefer double‑submit or signed tokens (JWT‑style) to avoid session DB bottlenecks.
• Token revocation: If a user logs out from one device, all tokens should be invalidated. This requires a revocation list or short token lifetimes.
• Cross‑domain: When services span subdomains, SameSite=None; Secure is mandatory, and CSRF tokens must be propagated securely.
• Monitoring: Aggregate CSRF failures per endpoint; a sudden spike may indicate an attack.
• Cost/performance: Token generation is cheap, but storing tokens in Redis or a DB adds cost. Evaluate whether the added security outweighs the operational overhead.
• When NOT to use: Purely stateless APIs that use bearer tokens (OAuth2, JWT) are not vulnerable to CSRF, so CSRF protection is unnecessary there.

Design decisions

9. Interview questions

10. Hands‑on task

Task: Add CSRF protection to an existing Next.js API route that updates a user’s profile.

1. Install next-csrf or use csurf with a custom API route.
2. Generate a CSRF token on the server and expose it to the client (e.g., via a /csrf-token endpoint).
3. In the client, fetch the token and include it in the X-CSRF-Token header when submitting the form.
4. Verify that a request without the token receives a 403.
5. Commit the changes and write a short README explaining how the CSRF flow works.

11. Quick revision

• CSRF = Cross‑Site Request Forgery: forged authenticated requests.
• SameSite cookie attribute reduces CSRF but is not sufficient.
• Synchronizer token pattern: server stores token; client submits it back.
• Double‑submit cookie: token in cookie + header; stateless.
• Token must be unique per user/session and rotated on login/logout.
• Validate token before performing any state‑changing operation.
• CSRF does not protect GET requests; they should be idempotent.
• Use Secure flag on cookies; serve over HTTPS.
• Log CSRF failures; monitor for spikes.
• In SPAs, read the token from a cookie or meta tag and send it in a header.
• For JWT bearer token APIs, CSRF is not a concern.

12. References

• OWASP CSRF Prevention Cheat Sheet
• MDN Web Docs – SameSite cookie attribute
• Express csurf middleware
• Next.js API Routes
• FastAPI CSRF protection
• MDN – CSRF