diff --git a/assets/agw-docs/pages/security/csrf.md b/assets/agw-docs/pages/security/csrf.md index 87f52701e..404d5b985 100644 --- a/assets/agw-docs/pages/security/csrf.md +++ b/assets/agw-docs/pages/security/csrf.md @@ -8,6 +8,10 @@ According to [OWASP](https://community.owasp.org/attacks/csrf), CSRF is defined To help prevent CSRF attacks, you can enable CSRF protection for your gateway or a specific route. For each route that you apply the CSRF policy to, the filter checks to make sure that a request's origin matches its destination. If the origin and destination do not match, a 403 Forbidden error code is returned. +{{< version exclude-if="1.6.x,1.5.x,1.4.x,1.3.x,1.2.x,1.1.x,1.0.x" >}} +For requests without a `Sec-Fetch-Site` header, the policy compares the host and port in the `Origin` header with the request `Host` header. The policy ignores the scheme, so the origin `https://www.example.com` matches a plain HTTP request to `www.example.com`. The policy treats an `Origin: null` header as a cross-origin request, and rejects it unless `additionalOrigins` contains `null`. +{{< /version >}} + Review the following diagram to see an example CSRF request flow: ```mermaid sequenceDiagram @@ -74,7 +78,7 @@ Configure an {{< reuse "agw-docs/snippets/policy.md" >}} to enable CSRF protecti | Field | Description | |-------|-------------| | `csrf` | Enables CSRF protection for the targeted Gateway or routes. When configured, all cross-origin requests are validated. | - | `additionalOrigins` | List of additional origins that are allowed to make requests to your app beyond the same-origin requests. This is useful for trusted partners, subdomains, or CDNs. Origins cannot include wildcards. | + | `additionalOrigins` | List of additional origins that are allowed to make requests to your app beyond the same-origin requests. This is useful for trusted partners, subdomains, or CDNs. Origins cannot include wildcards.{{< version exclude-if="1.6.x,1.5.x,1.4.x,1.3.x,1.2.x,1.1.x,1.0.x" >}} To allow requests that send an `Origin: null` header, add `null` to this list.{{< /version >}} | {{< doc-test paths="csrf" >}} diff --git a/content/docs/standalone/main/documentation/configuration/security/csrf.md b/content/docs/standalone/main/documentation/configuration/security/csrf.md index 69f742753..d0742b639 100644 --- a/content/docs/standalone/main/documentation/configuration/security/csrf.md +++ b/content/docs/standalone/main/documentation/configuration/security/csrf.md @@ -24,6 +24,8 @@ According to [OWASP](https://community.owasp.org/attacks/csrf), CSRF is defined To help prevent CSRF attacks, the CSRF policy implements a multi-layered validation approach to allow or block requests based on their properties. The policy checks that the request's origin matches its destination. If the origin and destination do not match, a 403 Forbidden error code is returned. Unlike CORS, CSRF protection works with all HTTP clients, not just browsers. +For requests without a `Sec-Fetch-Site` header, the policy compares the host and port in the `Origin` header with the request `Host` header. The policy ignores the scheme, so the origin `https://www.example.com` matches a plain HTTP request to `www.example.com`. The policy treats an `Origin: null` header as a cross-origin request, and rejects it unless `additionalOrigins` contains `null`. + Review the following diagram to see an example CSRF request flow: ```mermaid sequenceDiagram @@ -59,7 +61,7 @@ sequenceDiagram Allowed requests are as follows. - Safe methods (`GET`, `HEAD`, `OPTIONS`) from any origin -- Same-origin requests (`Origin` matches `Host`) +- Same-origin requests, where the host and port in `Origin` match `Host`, regardless of scheme - Requests from origins in `additionalOrigins` - Requests with `Sec-Fetch-Site: same-origin` or `Sec-Fetch-Site: none` @@ -69,6 +71,7 @@ Blocked requests, which receive a `403 Forbidden` response with the message "CSR - Cross-site requests with `Sec-Fetch-Site: cross-site` (unless trusted) - Cross-site requests where `Origin` doesn't match `Host` (unless trusted) +- Requests without `Sec-Fetch-Site` and with `Origin: null` (unless trusted) - Malformed `Origin` headers in cross-site contexts > [!NOTE] @@ -158,7 +161,7 @@ agentgateway -f config-mcp.yaml --validate-only {{< /doc-test >}} The `additionalOrigins` setting is a list of trusted origins allowed to make cross-site requests. -- Format: `"scheme://host[:port]"` +- Format: `"scheme://host[:port]"`. To allow requests that send an `Origin: null` header, add `"null"`. - Examples: `"https://www.example.com"`, `"http://localhost:3000"` For strict CSRF protection to prevent all cross-site requests, set `additionalOrigins` to an empty list, as shown in the following route-level policy.