From dd2cff6a136a0a4e05658ede26a5096170c26daa Mon Sep 17 00:00:00 2001 From: Dmitry Verkhoturov Date: Sun, 20 Oct 2024 23:15:24 +0100 Subject: [PATCH] Clarify ALLOWED_HOSTS description and usage This clarifies that the parameter sets CSP 'frame-ancestors' to limit hosts allowed to embed comments. The commit also improves the documentation on how to use ALLOWED_HOSTS with AUTH_SAME_SITE for different setup scenarios. We might want to change AUTH_SAME_SITE to `strong` in v2.0 as it works on the subdomain of the same site as well as current Lax option. --- backend/app/cmd/server.go | 2 +- site/src/docs/configuration/parameters/index.md | 2 +- site/src/docs/manuals/separate-domain/index.md | 12 +++++++----- site/src/docs/manuals/subdomain/index.md | 4 ++-- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/backend/app/cmd/server.go b/backend/app/cmd/server.go index a0bbeef1..9b9f3de2 100644 --- a/backend/app/cmd/server.go +++ b/backend/app/cmd/server.go @@ -85,7 +85,7 @@ type ServerCommand struct { EnableEmoji bool `long:"emoji" env:"EMOJI" description:"enable emoji"` SimpleView bool `long:"simple-view" env:"SIMPLE_VIEW" description:"minimal comment editor mode"` ProxyCORS bool `long:"proxy-cors" env:"PROXY_CORS" description:"disable internal CORS and delegate it to proxy"` - AllowedHosts []string `long:"allowed-hosts" env:"ALLOWED_HOSTS" description:"limit hosts/sources allowed to embed comments" env-delim:","` + AllowedHosts []string `long:"allowed-hosts" env:"ALLOWED_HOSTS" description:"limit hosts/sources allowed to embed comments via CSP 'frame-ancestors''" env-delim:","` SubscribersOnly bool `long:"subscribers-only" env:"SUBSCRIBERS_ONLY" description:"enable commenting only for Patreon subscribers"` DisableSignature bool `long:"disable-signature" env:"DISABLE_SIGNATURE" description:"disable server signature in headers"` DisableFancyTextFormatting bool `long:"disable-fancy-text-formatting" env:"DISABLE_FANCY_TEXT_FORMATTING" description:"disable fancy comments text formatting (replacement of quotes, dashes, fractions, etc)"` diff --git a/site/src/docs/configuration/parameters/index.md b/site/src/docs/configuration/parameters/index.md index 6e36fbf8..a3cddc01 100644 --- a/site/src/docs/configuration/parameters/index.md +++ b/site/src/docs/configuration/parameters/index.md @@ -154,7 +154,7 @@ services: | emoji | EMOJI | `false` | enable emoji support | | simple-view | SIMPLE_VIEW | `false` | minimized UI with basic info only | | proxy-cors | PROXY_CORS | `false` | disable internal CORS and delegate it to proxy | -| allowed-hosts | ALLOWED_HOSTS | enable all | limit hosts/sources allowed to embed comments | +| allowed-hosts | ALLOWED_HOSTS | enable all | limit hosts/sources allowed to embed comments via CSP 'frame-ancestors' | | address | REMARK_ADDRESS | all interfaces | web server listening address | | port | REMARK_PORT | `8080` | web server port | | web-root | REMARK_WEB_ROOT | `./web` | web server root directory | diff --git a/site/src/docs/manuals/separate-domain/index.md b/site/src/docs/manuals/separate-domain/index.md index 83815f90..28cee01b 100644 --- a/site/src/docs/manuals/separate-domain/index.md +++ b/site/src/docs/manuals/separate-domain/index.md @@ -10,17 +10,19 @@ Unless discussion [#1139](https://github.com/umputun/remark42/discussions/1139) ### Setup -Set `ALLOWED_HOSTS='self',example1.org,example2.org` with your domain names and `AUTH_SAME_SITE=none`. The `'self'` value means "domain which Remark42 is installed on" so you don't need to write it twice. +Set `ALLOWED_HOSTS="'self',example1.org,example2.org"` with your domain names and `AUTH_SAME_SITE=none`. + +The `'self'` in `ALLOWED_HOSTS` value means "domain where Remark42 is installed on" and needed if you want `remark42.example.com/web/` to work in case you want to test something with it. ### Technical details -`ALLOWED_HOSTS` sets CSP [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors), which, once enabled, limits the domains where Remark42 would work. The default value is not set so that it would work on any domain. +`ALLOWED_HOSTS` sets CSP [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors), which, once enabled, limits the domains where Remark42 would work. The default value is `*` so that it would work on any domain`. -`AUTH_SAME_SITE` sets the [SAME_SITE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) attribute for authorisation cookies, allowing Remark42 either on the original domain and subdomains there (default value, not set which equals to `Lax`) or allows setting authorisation cookies on any domain where remark42 is shown (`None` setting). +`AUTH_SAME_SITE` sets the [SAME_SITE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) attribute for authorisation cookies, allowing Remark42 either on the original domain and subdomains there (default value, which equals to `Lax`) or allows setting authorisation cookies on any domain where remark42 is shown (`None` setting). Here are all possible combinations of these two: -- Default setup with unaltered variables: comments are shown on any domain, but the authorisation wouldn't work anywhere, but on the same domain Remark42 is installed on and subdomains of it. -- `ALLOWED_HOSTS` set to a set of domains: comments are shown only on listed domains, authorisation wouldn't work anywhere, but on the same domain Remark42 is installed on and subdomains of it. +- Default setup with unaltered variables: comments are shown on any domain, but the authorisation wouldn't work anywhere, except on the same domain Remark42 is installed on and subdomains of it. +- `ALLOWED_HOSTS` set to a set of domains: comments are shown only on listed domains, and authorisation wouldn't work anywhere, expect on the same domain Remark42 is installed on and subdomains of it. - `AUTH_SAME_SITE` set to `None`: comments are shown on any domain. The authorisation would work anywhere. - `ALLOWED_HOSTS` set to a set of domains and `AUTH_SAME_SITE` set to `None`: comments are shown on listed domains. The authorisation would work on all of them. diff --git a/site/src/docs/manuals/subdomain/index.md b/site/src/docs/manuals/subdomain/index.md index 2ac449f7..91010770 100644 --- a/site/src/docs/manuals/subdomain/index.md +++ b/site/src/docs/manuals/subdomain/index.md @@ -8,9 +8,9 @@ All documentation examples show configurations with remark42 on its own subdomai - The frontend URL looks like this: `s.src = 'https://example.com/remark42/web/embed.js;` -- The backend `REMARK_URL` parameter will be `https://example.com/remark42` +- The backend `REMARK_URL` parameter will be `https://example.com/remark42`. `ALLOWED_HOSTS="'self'"` and `AUTH_SAME_SITE=strict` to make comments work only from the same domain. -- And you also need to slightly modify the callback URL for the social media login API's: +- And you also need to slightly modify the callback URL for the social media login APIs: - Facebook Valid OAuth Redirect URIs: `https://example.com/remark42/auth/facebook/callback` - Google Authorized redirect URIs: `https://example.com/remark42/auth/google/callback` - GitHub Authorised callback URL: `https://example.com/remark42/auth/github/callback`