docs: CORS

dunglas · Mar 30, 2021 · e8c1391 · e8c1391
1 parent c5ccf94
commit e8c1391
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 3 deletions.
diff --git a/docs/hub/config.md b/docs/hub/config.md
@@ -46,7 +46,7 @@ The following Mercure-specific directives are available:
 | `subscriber_jwt <key> [<algorithm>]` | the JWT key and algorithm to use for subscribers, can contain [placeholders](https://caddyserver.com/docs/conventions#placeholders)                                                                                                            |                     |
 | `anonymous`                          | allow subscribers with no valid JWT to connect                                                                                                                                                                                                 | `false`             |
 | `publish_origins <origins...>`       | a list of origins allowed publishing, can be `*` for all (only applicable when using cookie-based auth)                                                                                                                                        |                     |
-| `cors_origins <origin...>`           | a list of allowed CORS origins, can be `*` for all                                                                                                                                                                                             |                     |
+| `cors_origins <origin...>`           | a list of allowed CORS origins, ([troubleshoot CORS issues](troubleshooting.md#cors-issues))                                                                                                                                                   |                     |
 | `subscriptions`                      | expose the subscription web API and dispatch private updates when a subscription between the Hub and a subscriber is established or closed. The topic follows the template `/.well-known/mercure/subscriptions/{topicSelector}/{subscriberID}` |                     |
 | `heartbeat`                          | interval between heartbeats (useful with some proxies, and old browsers), set to `0s` disable                                                                                                                                                  | `40s`               |
 | `transport_url <url>`                | URL representation of the transport to use. Use `local://local` to disabled history, (example `bolt:///var/run/mercure.db?size=100&cleanup_frequency=0.4`), see also [the cluster mode](cluster.md)                                            | `bolt://mercure.db` |
@@ -120,6 +120,8 @@ You can visualize and edit the content of the database using [boltdbweb](https:/
 
 ## Legacy Server
 
+**The legacy server is deprecated and will be removed in the next version. Consider upgrading to the Caddy-based build.**
+
 The legacy Mercure.rocks Hub is configurable using [environment variables](https://en.wikipedia.org/wiki/Environment_variable) (recommended in production, [twelve-factor app methodology](https://12factor.net/)), command line flags and configuration files (JSON, TOML, YAML, HCL, envfile and Java properties files are supported).
 
 Environment variables must be the name of the configuration parameter in uppercase.

diff --git a/docs/hub/troubleshooting.md b/docs/hub/troubleshooting.md
@@ -12,9 +12,13 @@
 
 For both the `publish` property, the array can be empty to publish only public updates. For both `publish` and `subscribe`, you can use `["*"]` to match all topics.
 
-## Browser Issues
+## CORS Issues
 
-If subscribing to the `EventSource` in the browser doesn't work (the browser instantly disconnects from the stream or complains about CORS policy on receiving an event), check that you've set a proper value for `cors_origins` in the `Caddyfile`. It's fine to use `cors_origins *` for local development.
+If subscribing using `EventSource` doesn't work (the browser instantly disconnects from the stream or complains about CORS policy), check that you've set a proper value for `cors_origins` in the `Caddyfile`.
+
+Example: `cors_origins https://example.com https://example.net`.
+
+If you use an authorization mechanism (cookie or `Authorization` header), [you cannot set the value of `cors_origins` to `*`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Credentialed_requests_and_wildcards). You **must** explicitly set the list of allowed origins.
 
 ## URI Templates and Topics