diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md
index ea3d32bbb..4185a9d65 100644
--- a/docs/configuring-well-known.md
+++ b/docs/configuring-well-known.md
@@ -23,19 +23,29 @@ To make things easy for you to set up, this playbook generates and hosts the wel
 
 You have 2 options when it comes to installing the file on the base domain's server:
 
-1) (Option 1): **Copying the file manually** to your base domain's server
 
-All it takes is copying the `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`).
+### (Option 1): **Copying the file manually** to your base domain's server
 
-This is easy to do and possibly your only choice if you can only host static files from the base domain's server.
-It is, however, a little fragile, as future updates performed by this playbook may regenerate the well-known file and you may need to notice that and copy it again.
+**Hint**: Option 2 (below) is generally a better way to do this. Make sure to go with that one, if possible.
 
-2) (Option 2): **Setting up reverse-proxying** of the well-known file from the base domain's server to the Matrix server.
+All you need to do is:
+
+- copy the `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`).
+
+- set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Riot) may fail to work.
+
+This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server.
+It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known file and you may need to notice that and copy it again.
+
+
+### (Option 2): **Setting up reverse-proxying** of the well-known file from the base domain's server to the Matrix server
 
 This option is less fragile and generally better.
 
 On the base domain's server (e.g. `example.com`), you can set up reverse-proxying, so that any access for the `/.well-known/matrix` location prefix is forwarded to the Matrix domain's server (e.g. `matrix.example.com`).
 
+With this method, you **don't need** to add special HTTP headers for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reasons (like `Access-Control-Allow-Origin`), because your Matrix server (where requests ultimately go) will be configured by this playbook correctly.
+
 **For nginx**, it would be something like this:
 
 ```nginx
diff --git a/roles/matrix-server/tasks/self_check/self_check_well_known.yml b/roles/matrix-server/tasks/self_check/self_check_well_known.yml
index 96c3724e8..ea3bae4bc 100644
--- a/roles/matrix-server/tasks/self_check/self_check_well_known.yml
+++ b/roles/matrix-server/tasks/self_check/self_check_well_known.yml
@@ -17,9 +17,14 @@
     msg: "Failed checking well-known is configured at `{{ hostname_matrix }}` (checked endpoint: `{{ well_known_url_matrix }}`). Is port 443 open in your firewall? Full error: {{ result_well_known_matrix }}"
   when: "result_well_known_matrix.failed or 'json' not in result_well_known_matrix"
 
+- name: Fail if .well-known not CORS-aware on the matrix hostname
+  fail:
+    msg: "Well-known serving for `{{ hostname_matrix }}` (checked endpoint: `{{ well_known_url_matrix }}`) is not CORS-aware. The file needs to be served with an Access-Control-Allow-Origin header set."
+  when: "'access_control_allow_origin' not in result_well_known_matrix"
+
 - name: Report working .well-known on the matrix hostname
   debug:
-    msg: "well-known is configured at `{{ hostname_matrix }}` (checked endpoint: `{{ well_known_url_matrix }}`)"
+    msg: "well-known is configured correctly for `{{ hostname_matrix }}` (checked endpoint: `{{ well_known_url_matrix }}`)"
 
 
 - name: Check .well-known on the identity hostname
@@ -34,13 +39,17 @@
     msg: "Failed checking well-known is configured at `{{ hostname_identity }}` (checked endpoint: `{{ well_known_url_identity }}`). Is port 443 open in your firewall? Full error: {{ result_well_known_identity }}"
   when: "result_well_known_identity.failed or 'json' not in result_well_known_identity"
 
-- name: Report working .well-known on the identity hostname
-  debug:
-    msg: "well-known is configured at `{{ hostname_identity }}` (checked endpoint: `{{ well_known_url_identity }}`)"
-
+- name: Fail if .well-known not CORS-aware on the identity hostname
+  fail:
+    msg: "Well-known serving for `{{ hostname_identity }}` (checked endpoint: `{{ well_known_url_identity }}`) is not CORS-aware. The file needs to be served with an Access-Control-Allow-Origin header set. See docs/configuring-well-known.md"
+  when: "'access_control_allow_origin' not in result_well_known_identity"
 
 # For people who manually copy the well-known file, try to detect if it's outdated
 - name: Fail if well-known is different on matrix hostname and identity hostname
   fail:
     msg: "The well-known files at `{{ hostname_matrix }}` and `{{ hostname_identity }}` are different. Perhaps you copied the file manually before and now it's outdated?"
   when: "result_well_known_matrix.json|to_json != result_well_known_identity.json|to_json"
+
+- name: Report working .well-known on the identity hostname
+  debug:
+    msg: "well-known is configured correctly for `{{ hostname_identity }}` (checked endpoint: `{{ well_known_url_identity }}`)"
diff --git a/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 b/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2
index 096249e08..2b4c0231a 100644
--- a/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2
+++ b/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2
@@ -43,6 +43,7 @@ server {
 		root {{ matrix_static_files_base_path }};
 		expires 1m;
 		default_type application/json;
+		add_header Access-Control-Allow-Origin *;
 	}
 
 	{% if matrix_corporal_enabled and matrix_corporal_http_api_enabled %}