[security.csrf]

Cross-site request protection: unsafe requests from other sites are refused in Rust before the body is read or any app code runs.

[security.csrf]
trusted_origins = ["https://admin.example.com"]
exempt = ["/api/webhooks/*rest", "/auth/callback/apple"]

On by default with no configuration. It covers every method except GET, HEAD, OPTIONS and TRACE - page actions, route handlers, form posts - and its two lists also apply to the WebSocket origin check.

Reference

Behavior

Each unsafe request is judged on headers browsers attach, in this order:

• The host the client addressed is the Host header, or a trusted proxy's X-Forwarded-Host / Forwarded: host= (see [server] trusted_proxies).
• A refused request gets 403 with Cache-Control: no-store and a plain-text body naming the keys to change:

403 Forbidden: cross-site POST blocked by CSRF protection - the browser sent it from https://evil.example (cross-site).
If that origin is yours, add it to [security.csrf] trusted_origins in gio.toml; to accept cross-site requests on a path (webhooks, OAuth/OIDC form_post or SAML callbacks, 3-D Secure payment returns), add the path to [security.csrf] exempt.

• Each refused origin is logged once at warn level (up to 64 distinct ones), then at debug, so a page looping forged requests cannot flood the log.
• Rust's own /_gio endpoints are not covered: they have their own checks (the revalidation endpoint uses a bearer token).

Startup warnings

Errors

• [security.csrf] trusted_origins entry "admin.example.com" is not an origin such as "https://admin.example.com" (scheme http or https, no path)
• [security.csrf] exempt entry "api/webhooks": pattern must start with '/': api/webhooks

Examples

An admin app on another origin

[security.csrf]
trusted_origins = ["https://admin.example.com", "http://localhost:5173"]

Sign in with Apple form_post callback

Apple posts the user's browser back to your callback from its own site, so the browser labels the request cross-site. Exempt the path; the handler verifies the state and the token itself:

[security.csrf]
exempt = ["/auth/callback/apple"]

Forms with their own tokens

[security.csrf]
enabled = false          # every form posts a token the app verifies (logs a warning)

Good to know

• The check runs before the body is read, before rules, routing and Node - a forged request never costs a render. It runs inside rate limiting, so forged requests still use up budget.
• Behind a proxy that rewrites Host to an internal name, every same-origin browser request looks cross-origin. Pass the host through (nginx proxy_set_header Host $host), or list the proxy in trusted_proxies so its X-Forwarded-Host counts.
• Keep GET handlers free of side effects and keep session cookies SameSite=Lax: the check covers unsafe methods only.

Not configurable

• Sec-Fetch-Site: same-site is refused like cross-site: a sibling subdomain can be controlled by someone else. List such origins in trusted_origins.
• Requests with neither Sec-Fetch-Site nor Origin always pass.

Related

• Security guide: CSRF protection
• [security.websocket]
• [security]
• Forms & Mutations
• Turning Protections On and Off

Version history