CSRF protection for modern JSON APIs

The State of CSRF in JSON APIs

A Cross-Site Request Forgery attack occurs when a malicious web context tricks an authenticated user's browser into performing an unwanted action on a trusted site. The OWASP Cross-Site Request Forgery Prevention Cheat Sheet notes that if a target user is authenticated, unprotected sites cannot distinguish between legitimate authorized requests and forged authenticated requests. Because browsers automatically include session cookies in cross-origin requests, relying solely on cookies for API authentication exposes state-changing endpoints to exploitation unless specific challenge-response mechanisms are implemented.

Modern JSON APIs face unique architectural constraints compared to traditional server-rendered web applications. API-driven sites frequently operate statelessly or decouple the frontend presentation layer from the backend service, rendering standard form-based synchronizer token injection difficult. Furthermore, while Cross-Site Scripting vulnerabilities can bypass all CSRF mitigations by directly reading tokens or forging requests from the trusted origin, CSRF protections remain an absolute necessity for web applications relying on cookie-based sessions. Protocol-specific defenses must establish explicit proof of origin and explicit proof of client intent.

Evaluating Synchronizer Tokens

The synchronizer token pattern relies on generating a secret, unpredictable token on the server and synchronizing it with the client state. According to OWASP guidance, tokens must be generated via a secure cryptographic method and remain unique per user session. The client must then transmit this token back to the server via a custom request header or within the JSON payload. Crucially, the token must never be transmitted within a cookie for the synchronized pattern, nor should it be leaked in server logs or URL parameters.

While per-request tokens offer a minimal time window for exploitation, OWASP highlights that they introduce significant usability concerns. For example, browser back-button navigation can be hindered because the previous view may hold an invalidated token, resulting in false positive security events on the server. Because maintaining server-side state for token validation is often fundamentally incompatible with horizontally scaled, stateless JSON APIs, alternative patterns are frequently required for modern architectures.

The Signed Double-Submit Cookie Pattern

When maintaining server-side state is problematic, OWASP explicitly recommends the Signed Double-Submit Cookie pattern. The naive double-submit cookie pattern, which merely verifies that a random cookie value matches a submitted request header, is actively discouraged. Naive implementations are vulnerable to cookie injection attacks where an attacker controlling a sibling subdomain or a plaintext network environment can plant a known cookie and bypass the check entirely.

The recommended signed approach requires binding the CSRF token explicitly to session-specific data using Hash-based Message Authentication Codes. To implement this securely, the system computes an HMAC-SHA-256 hash over an unambiguous encoding of a session-dependent value, such as the server-side session ID, combined with a cryptographically random anti-collision value. This HMAC and the random value are included in the token, which is set as a Secure cookie. Upon receiving a protected API request, the server reads the token from a custom submitted header, extracts the components, recomputes the HMAC using the current session ID, and performs a constant-time comparison to validate authenticity.

• Generate a session-dependent value valid only for the entirety of the authenticated session.
• Generate a cryptographically random value for anti-collision purposes to ensure unique hashes.
• Compute the HMAC-SHA-256 hash over the combined values using a server-side secret cryptographic key.
• Transmit the token as a Secure cookie and require its return in a custom HTTP header.
• Verify the HMAC using a constant-time comparison function before processing state-changing operations.

Fetch Metadata Request Headers

Fetch Metadata request headers provide a lightweight, modern mechanism to enforce CSRF protection without client-side token coordination. Supported in major browsers since March 2023, these headers deliver immutable context regarding the origin of an HTTP request. OWASP documentation identifies Sec-Fetch-Site as the primary signal for CSRF protection, indicating whether the request is same-origin, same-site, cross-site, or none. By inspecting this header, API servers can deterministically block obvious cross-origin state-changing requests.

A robust Fetch Metadata policy dictates that if Sec-Fetch-Site equals cross-site, the server must reject unsafe HTTP methods such as POST, PUT, PATCH, and DELETE. Requests indicating same-origin are inherently trusted. Handling same-site requests requires assessing the threat model; they should only be permitted if the organization explicitly trusts all sibling subdomains. Because legacy browsers may not populate Sec-Fetch headers, developers must implement a fail-safe fallback mechanism, such as reverting to the signed double-submit cookie pattern, to ensure comprehensive coverage without breaking compatibility.

Implementation Tradeoffs and Test Matrix

Implementing CSRF defenses involves architectural tradeoffs. The signed double-submit pattern guarantees stateless operation but introduces cryptographic overhead for every request and relies heavily on absolute secrecy of the server-side HMAC key. A failure mode occurs if an attacker compromises the secret key or if a vulnerability allows session fixation, rendering the HMAC generation predictable. Fetch Metadata relies entirely on client browser enforcement; a failure mode here involves legacy clients bypassing the check if the server policy fails open instead of failing closed.

The following hypothetical synthetic test matrix illustrates a secure policy evaluation for a JSON API endpoint handling a POST request. The expected outcomes validate both the Signed Double-Submit token and Fetch Metadata logic. The system is designed to reject unsafe requests immediately.

• Request: POST /api/data | Headers: None | Cookie: valid_session | Expected: Denied (Missing intent proof)
• Request: POST /api/data | Headers: Sec-Fetch-Site: cross-site | Cookie: valid_session | Expected: Denied (Policy violation)
• Request: POST /api/data | Headers: X-CSRF-Token: naive_unsigned_token | Cookie: session+naive_cookie | Expected: Denied (Fails HMAC check)
• Request: POST /api/data | Headers: Sec-Fetch-Site: same-origin, X-CSRF-Token: valid_hmac | Expected: Allowed (Complete verification)
• Request: GET /api/data | Headers: Sec-Fetch-Site: cross-site | Expected: Allowed (Safe method exemption)

Sources and Evidence Limits

This article is provided for educational and architectural planning purposes only. It is not an instruction manual for attacking third-party systems. Security implementers must rely on their specific framework capabilities and conduct dedicated threat modeling when deploying cryptographic token patterns.

Drafted with Gemini and checked for source links, advisory identifiers, structure and unsupported product claims. Examples are synthetic and are not scan results.

Drafted with Gemini and checked for source links, advisory identifiers, structure and unsupported product claims. Examples are synthetic and are not scan results.

• OWASP Cross-Site Request Forgery Prevention Cheat Sheet