Browsers attach a user's cookies to requests that other sites trigger, so every authenticated endpoint has to decide whether a request really came from its own pages. Fetch Metadata request headers (Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest and Sec-Fetch-User) give the server that context on every request, and a short server-side rule called a Resource Isolation Policy can reject cross-site requests before they reach application code. This guide explains what each header carries, how to write and roll out a policy in middleware or at a reverse proxy, how it compares with CSRF tokens, SameSite cookies and origin checks, and how to measure it. It is written for web developers, application security engineers and the platform teams who own gateways and CDNs. Response headers such as COOP, COEP and CORP are covered in the Permissions Policy, COOP, COEP and CORP Guide; this page is about the request side.
Key takeaways
- Sec-Fetch-Site is the primary signal. It tells the server whether the request came from the same origin, the same site, another site, or directly from the user (
none), and the OWASP CSRF Prevention Cheat Sheet makes it the core of a Fetch Metadata policy. - A Resource Isolation Policy is a few lines of code. Allow same-origin and user-initiated requests, allow simple top-level GET navigations, exempt the endpoints meant for other sites, and reject the rest with HTTP 403.
- The missing-header case is a design decision. Older guidance allowed requests without the headers; OWASP now treats a fallback to Origin verification as mandatory and recommends blocking on sensitive endpoints.
- It covers more than CSRF. Rejecting unexpected cross-site loads also cuts off cross-site script inclusion, many XS-Leaks and timing attacks that tokens cannot stop.
- Roll out in report-only mode first. Log would-be rejections, build the exemption list from real traffic, add the headers to
Vary, then enforce.
What Fetch Metadata headers are
Fetch Metadata Request Headers is a W3C Web Application Security Working Group specification (shown as a Working Draft on the W3C repository when checked on 27 October 2026). The browser adds the headers itself; page script cannot set or forge them, because names starting with Sec- are forbidden request headers. The specification's own motivation is that some cross-site attacks are hard to prevent in application code ("simple" CSRF) and others are practically impossible to prevent there (cross-site search and timing attacks), so the server needs context about how a request was made in order to refuse it early, potentially at a reverse proxy or CDN.
| Header | What it tells the server | Values defined | Use in a policy |
|---|---|---|---|
Sec-Fetch-Site | Relationship between the initiator and the target | same-origin, same-site, cross-site, none | Main allow or reject decision |
Sec-Fetch-Mode | The request mode | cors, navigate, no-cors, same-origin, websocket | Distinguish top-level navigation from resource loads and API calls |
Sec-Fetch-Dest | Where the response will be used | Fetch destinations such as document, iframe, image, script, worker, empty (fetch and XHR) | Block framing or script inclusion of endpoints that should never be loaded that way |
Sec-Fetch-User | Whether a navigation was triggered by user activation | ?1, sent only on navigations and only when true | Optional extra signal for sensitive navigations |
- Redirect chains: the browser computes
Sec-Fetch-Siteacross the whole redirect chain. If any hop was cross-site, the final request is labelledcross-site, even when the chain ends back on the original origin. An open redirect on your own site therefore cannot launder a cross-site request into a same-origin one. - The
nonevalue: sent when the user started the request directly, for example by typing a URL, opening a bookmark or dragging a link in from outside the browser. - Forward compatibility: the specification and OWASP both say servers should ignore a header that carries a value they do not recognise, rather than rejecting the request.
- Browser support: web.dev lists
Sec-Fetch-SiteandSec-Fetch-Modefrom Chrome 76, Edge 79, Firefox 90 and Safari 16.4, andSec-Fetch-Destfrom Chrome 80. OWASP notes support in all major browsers since March 2023, including iOS and Android web views.
Writing a Resource Isolation Policy
The Resource Isolation Policy described on web.dev, and refined in the OWASP CSRF Prevention Cheat Sheet, is an ordered list of rules evaluated before authentication and before any business logic. Evaluating it first matters: if the server does real work before rejecting a cross-site request, response timing can still leak information.
- Header absent: decide explicitly (see the next section). Do not let absence silently fall through to "allow" on sensitive endpoints.
- Allow
same-origin: requests from your own pages. - Decide on
same-site: allow it only if you trust every sibling subdomain under the same registrable domain. A forgotten marketing subdomain or one with a dangling CNAME is part of "same site". OWASP's example treatssame-siteas untrusted for state-changing methods by default. - Allow
none: user-driven navigations such as bookmarks and typed URLs. - Allow simple top-level navigations: cross-site
GETrequests withSec-Fetch-Mode: navigate, except whereSec-Fetch-Destisobjectorembed. This keeps inbound links working. A stricter "navigation isolation" variant allows cross-site navigations only to a short list of landing pages. - Allow exempted endpoints: paths that are meant to be used cross-site, such as CORS-enabled APIs, public assets, OAuth and SAML endpoints that receive cross-site form posts, and webhook receivers. Keep this list small and reviewed.
- Reject everything else: return 403 with a generic body and log the decision.
OWASP adds two refinements. First, if the application performs state changes on safe methods (GET, HEAD or OPTIONS), list those endpoints and reject cross-site requests to them too, even though a GET would otherwise pass. Second, where a policy depends on these headers, the response must carry Vary: Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest (plus whatever else it already varies on) so a shared cache does not serve a response produced for one context to another. The specification gives Vary: Accept-Encoding, Sec-Fetch-Site as its example.
Targeted rules with Sec-Fetch-Dest
| Endpoint type | Expected destination | Rule | What it blocks |
|---|---|---|---|
| JSON API | empty | Reject cross-site requests whose destination is script, image or document | Cross-site script inclusion and error-event probing |
| Account pages | document | Reject iframe, frame, object and embed from other sites | Framing-based leaks (alongside frame-ancestors) |
| Authenticated downloads and images | image, video, document | Allow only same-origin, or set a restrictive CORP header | Hotlinking of private resources and existence probing |
| Search and filter endpoints | empty or document | Reject cross-site no-cors loads | Cross-site search and timing XS-Leaks |
| Public static assets | Any | Exempt | Nothing, by design |
ASVS 5.0 recognises this approach directly: V3.5.3 (Level 1) allows strict validation of Sec-Fetch-* headers as an alternative to keeping sensitive functions off safe methods, and V3.5.8 (Level 3) asks that authenticated resources can be loaded or embedded on the user's behalf only when intended, by validating Sec-Fetch-* or by setting a restrictive Cross-Origin-Resource-Policy.
Handling requests without the headers
This is where published guidance has moved. The 2020 web.dev policy starts with "allow requests without Fetch Metadata", on the reasoning that the browser simply does not support it. The current OWASP cheat sheet says a fallback to standard origin verification is a mandatory requirement for any Fetch Metadata implementation, and gives two options when Sec-Fetch-* is absent:
- Fail-safe (recommended for sensitive endpoints): treat absence as unknown and block the request.
- Fail-open (compatibility first): fall back to checking the
Origin(orReferer) header against the expected origin, CSRF tokens, or another validation step.
Two populations send no Fetch Metadata: old or embedded browsers, and non-browser clients such as mobile apps, server-to-server integrations, scripts and monitoring probes. Non-browser clients do not carry ambient cookies from a victim's browser, so they are not a CSRF risk, but they usually authenticate with bearer tokens or API keys and should be routed to API endpoints that never accept cookie authentication. The cleanest design separates the two: cookie-authenticated browser routes enforce the policy fail-safe, and token-authenticated API routes do not depend on it. The Go standard library's http.CrossOriginProtection type (Go 1.25) shows a practical middle ground: it always allows safe methods, uses Sec-Fetch-Site or compares the Origin host with the Host header, treats requests with neither header as same-origin or non-browser, and offers AddTrustedOrigin and AddInsecureBypassPattern for exemptions, returning 403 on rejection.
Fetch Metadata compared with other CSRF and isolation controls
| Control | Protects against | Client changes | Main weakness | Best fit |
|---|---|---|---|---|
| Fetch Metadata policy | CSRF, XSSI, many XS-Leaks, timing attacks | None | Depends on the fallback for clients without the headers; same-site trust | Modern browser applications, central enforcement at a gateway |
| Synchronizer token | CSRF on state-changing requests | Forms and AJAX must carry the token | Implementation errors, token leakage in URLs or logs; no protection for reads | Stateful applications, legacy browser support |
| Double-submit cookie (signed) | CSRF | Client must echo the token | Naive versions are bypassable from a subdomain that can set cookies | Stateless services |
| SameSite cookies | Most cross-site cookie sending | None | Treats all same-site subdomains as trusted; Lax still sends on top-level GET | Baseline for every session cookie |
| Origin header verification | CSRF | None | Some requests omit or null the header | Fallback for Fetch Metadata |
| CORP response header | Cross-origin embedding of responses | None | Browser enforcement only, response is still generated | Private images, media and documents |
OWASP's summary order is useful as decision guidance: use your framework's built-in CSRF protection first; if the software targets only modern browsers, Fetch Metadata plus a fallback is sufficient on its own; stateful software otherwise uses synchronizer tokens and stateless software signed double-submit cookies; and SameSite cookies are a defence in depth layer, not the primary control. For high-risk actions such as payment approval or changing MFA, add user interaction (re-authentication) regardless. See the CSRF Prevention Guide and the Cookie Security Guide.
- Small teams: use the framework middleware (Go
CrossOriginProtection, or the built-in CSRF protection of your framework) rather than writing custom header logic. - Large estates: enforce a shared policy at the reverse proxy, API gateway or CDN edge, with per-application exemption lists owned by the application team and reviewed by security.
Defending against cross-site leaks
CSRF changes state; XS-Leaks infer state. An attacking page can embed a victim site's URL as a script or image and watch onload and onerror events, frame counts or timing to learn whether the user is logged in, which account they hold, or whether a search returned results. The OWASP XS Leaks Cheat Sheet shows both Sec-Fetch-Dest (reject iframe loads of a page) and Sec-Fetch-Site (reject cross-site calls to a user API) as server-side defences. Because the request is refused before the response is generated, the status code, size and timing an attacker could measure are the same for every user. Fetch Metadata does not protect window references opened by the attacker; for those, web.dev recommends Cross-Origin-Opener-Policy: same-origin, and framing should still be restricted with CSP frame-ancestors. See the Content Security Policy Guide and the Client-Side Security Guide.
Implementing and rolling out the policy
- Inventory endpoints: classify routes as cookie-authenticated browser pages, cookie-authenticated XHR and fetch endpoints, token-authenticated APIs, intentionally cross-site endpoints (OAuth and SAML callbacks, payment provider returns, webhooks, embeddable widgets) and public assets.
- Choose the enforcement point: application middleware gives route-level precision; a reverse proxy or gateway gives one policy for many services. Either way, run it before authentication and session loading.
- Deploy in report-only mode: compute the decision on every request and log it with the path, method and the four header values, but do not block. web.dev's author reported that most applications at Google were compatible and rarely needed exemptions; your logs will confirm whether that holds for you.
- Build the exemption list from evidence: add only endpoints that legitimately receive cross-site traffic, and record the owner and reason for each.
- Add
Vary: include the Fetch Metadata headers on responses whose content depends on them, and check CDN cache keys. - Enforce in rings: start with state-changing methods on high-value routes, then all cookie-authenticated routes, then
Sec-Fetch-Destrules for framing and script inclusion. - Test: automated tests should send requests with each
Sec-Fetch-Sitevalue and with the headers removed, and assert the expected allow or 403. Browser tests from a separate test origin confirm real behaviour. - Roll back safely: keep the policy behind a configuration flag that returns it to report-only, so a broken partner integration can be restored in minutes without removing the code.
Detection and measurement
Each rejection is a security event worth keeping. Log the decision, the rule that fired, the method, path, Sec-Fetch-* values and the Origin header, but not cookies or tokens. A cluster of cross-site rejections against one endpoint from many users usually means a malicious page or an unregistered integration; a sudden spike after a release usually means a new legitimate flow that needs an exemption.
- Coverage: percentage of cookie-authenticated routes behind the policy in enforce mode (target 100% for state-changing routes).
- Header presence: share of browser requests that arrive without
Sec-Fetch-Site; this sizes the fallback population. - Rejection rate: cross-site rejections per million requests, by route, trended weekly.
- False positives: support tickets or synthetic test failures caused by the policy after enforcement (target zero after the first ring).
- Exemption hygiene: number of exempt routes, each with an owner and a review date no older than 12 months.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| OWASP ASVS 5.0 | V3.5.1, V3.5.3, V3.5.8, V3.3.2 | Anti-forgery validation, Sec-Fetch-* as an alternative control, restricted embedding, SameSite cookies |
| MITRE CAPEC | CAPEC-62 Cross Site Request Forgery | Attack pattern the policy blocks |
| NIST SP 800-53 Rev. 5 | SC-23 Session Authenticity; AC-4 Information Flow Enforcement; SI-10 Information Input Validation | Protecting sessions from forged requests and enforcing which contexts may reach an endpoint |
| NIST CSF 2.0 | PR.PS-06; DE.CM-09 | Secure development practice; monitoring of software and runtime events |
Where identity fits
Every attack Fetch Metadata stops abuses an ambient credential: the session cookie the browser attaches automatically. Endpoints that authenticate with an explicit bearer token in an Authorization header are not exposed to classic CSRF, which is one more reason to keep machine and integration clients on token-authenticated APIs rather than letting them reuse browser session endpoints. Those tokens then need their own lifecycle controls. See the Session Hijacking and Cookie Theft Guide.
Common failure patterns
- Fail-open on missing headers everywhere: copying the original "allow if absent" rule onto sensitive endpoints without an Origin check, so any client that omits the headers bypasses the control.
- Trusting
same-siteby default: a takeover-prone or user-content subdomain becomes a launch point for "same-site" forged requests. - Running the check after authentication or work: the response is rejected, but timing differences have already leaked whether the user is logged in or the record exists.
- Forgetting
Vary: a CDN caches a 403 produced for a cross-site request and serves it to legitimate same-origin users, or caches the reverse. - Unbounded exemptions: whole path prefixes exempted to fix one partner integration, re-opening the routes the policy was meant to cover.
- State changes on GET: the default rule passes cross-site GET navigations, so a GET that changes state stays exploitable unless it is listed as sensitive.
Practitioner checklist
- Inventory routes by authentication type and list every endpoint that legitimately receives cross-site traffic.
- Implement the Resource Isolation Policy before authentication, in framework middleware or at the gateway.
- Decide and document the behaviour when
Sec-Fetch-*is absent, with an Origin check fallback and fail-safe on sensitive routes. - Treat
same-siteas untrusted for state-changing methods unless every sibling subdomain is controlled. - Add
Sec-Fetch-Destrules to block framing and script inclusion of authenticated pages and APIs. - Add the Fetch Metadata headers to
Varyand check CDN cache keys. - Run report-only for at least one full business cycle, then enforce in rings behind a rollback flag.
- Keep SameSite cookies, framework CSRF tokens and re-authentication for high-risk actions as additional layers.
- Log every rejection with the header values and review rejection trends and exemptions regularly.
Standards and references
- W3C: Fetch Metadata Request Headers
- OWASP: Cross-Site Request Forgery Prevention Cheat Sheet
- OWASP: XS Leaks Cheat Sheet
- OWASP: Application Security Verification Standard 5.0
- web.dev: Protect your resources from web attacks with Fetch Metadata
- Go: net/http CrossOriginProtection
- MITRE CAPEC: Cross Site Request Forgery
- NIST: SP 800-53 Rev. 5
Related NHI Mgmt Group resources: CSRF Prevention Guide · Permissions Policy, COOP, COEP and CORP Guide · Client-Side Security Guide · CORS Misconfiguration Guide · Security Headers Guide