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.
umputun · Oct 20, 2024 · dd2cff6 · dd2cff6
1 parent 68fe6eb
commit dd2cff6
Show file tree

Hide file tree

Showing 4 changed files with 11 additions and 9 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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`