diff options
| author | TGJ Gilmore <TracyGJG@users.noreply.github.com> | 2025-02-10 19:35:31 +0000 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2025-02-10 20:35:31 +0100 |
| commit | 72b425f5fb322f61009f8f5c0f761426d0887dc2 (patch) | |
| tree | ab83b79250d778fad1943cb3f3061ce1d985a618 | |
| parent | 46badfe0b1412561202186c2b2cd05053d71ea32 (diff) | |
| download | htmx-72b425f5fb322f61009f8f5c0f761426d0887dc2.tar.gz htmx-72b425f5fb322f61009f8f5c0f761426d0887dc2.zip | |
Documentation update to include the use of hx-headers to prevent CSRF (#3176)
* Documentation update to include the use of hx-headers to prevent CSRF
* Update hx-headers.md
Revised follow review.
| -rw-r--r-- | www/content/attributes/hx-headers.md | 2 | ||||
| -rw-r--r-- | www/content/docs.md | 19 |
2 files changed, 21 insertions, 0 deletions
diff --git a/www/content/attributes/hx-headers.md b/www/content/attributes/hx-headers.md index 58e9d4a8..8665ca6e 100644 --- a/www/content/attributes/hx-headers.md +++ b/www/content/attributes/hx-headers.md @@ -24,6 +24,8 @@ If you wish for `hx-headers` to *evaluate* the values given, you can prefix the security considerations, especially when dealing with user input such as query strings or user-generated content, which could introduce a [Cross-Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/) vulnerability. +* Whilst far from being a foolproof solution to [Cross-Site Request Forgery](https://owasp.org/www-community/attacks/csrf), the `hx-headers` attribute can support backend services to provide [CSRF prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html). For more information see the [CSRF Prevention](https://htmx.org/docs/#csrf-prevention) section. + ## Notes * `hx-headers` is inherited and can be placed on a parent element. diff --git a/www/content/docs.md b/www/content/docs.md index d891e82b..d67170ca 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -1660,6 +1660,25 @@ with application security. A full discussion of CSPs is beyond the scope of this document, but the [MDN Article](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) provide a good jumping off point for exploring this topic. +### CSRF Prevention + +The assignment and checking of CSRF tokens are typically backend responsibilities, but `htmx` can support returning the CSRF token automatically with every request using the `hx-headers` attribute. The attribute needs to be added to the element issuing the request or one of its ancestor elements. This makes the `html` and `body` elements effective global vehicles for adding the CSRF token to the `HTTP` request header, as illustarted below. + +```html +<html lang="en" hx-headers='{"X-CSRF-TOKEN": "CSRF_TOKEN_INSERTED_HERE"}'> + : +</html> +``` + +```html + <body hx-headers='{"X-CSRF-TOKEN": "CSRF_TOKEN_INSERTED_HERE"}'> + : + </body> +``` + +The above elements are usually unique in an HTML document and should be easy to locate within templates. + + ## Configuring htmx {#config} Htmx has some configuration options that can be accessed either programmatically or declaratively. They are |