deploy: e462950338

develop/print.html

@@ -6011,6 +6011,14 @@ set.</p>
 <p>This is primarily intended for use with the <code>register_new_matrix_user</code> script
 (see <a href="usage/configuration/../../setup/installation.html#registering-a-user">Registering a user</a>);
 however, the interface is <a href="usage/configuration/../../admin_api/register_api.html">documented</a>.</p>
+<p>Replacing an existing <code>registration_shared_secret</code> with a new one requires users
+of the <a href="usage/configuration/../../admin_api/register_api.html">Shared-Secret Registration API</a> to
+start using the new secret for requesting any further one-time nonces.</p>
+<blockquote>
+<p>⚠️ <strong>Warning</strong> – The additional consequences of replacing
+<a href="usage/configuration/config_documentation.html#macaroon_secret_key"><code>macaroon_secret_key</code></a> will apply in case it delegates
+to <code>registration_shared_secret</code>.</p>
+</blockquote>
 <p>See also <a href="usage/configuration/config_documentation.html#registration_shared_secret_path"><code>registration_shared_secret_path</code></a>.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">registration_shared_secret: &lt;PRIVATE STRING&gt;
@@ -6441,6 +6449,12 @@ access tokens via a query parameter.</p>
 </ul>
 <p>If none is specified, the <code>registration_shared_secret</code> is used, if one is given;
 otherwise, a secret key is derived from the signing key.</p>
+<blockquote>
+<p>⚠️ <strong>Warning</strong> – Replacing an existing <code>macaroon_secret_key</code> with a new one
+will lead to invalidation of access tokens for all guest users. It will also
+break unsubscribe links in emails sent before the change. An unlucky user
+might encounter a broken SSO login flow and would have to start again.</p>
+</blockquote>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">macaroon_secret_key: &lt;PRIVATE STRING&gt;
 </code></pre>
@@ -6459,6 +6473,8 @@ Synapse reads the secret key from the given file once at startup.</p>
 <p>A secret which is used to calculate HMACs for form values, to stop
 falsification of values. Must be specified for the User Consent
 forms to work.</p>
+<p>Replacing an existing <code>form_secret</code> with a new one might break the user consent
+page for an unlucky user and require them to reopen the page from a new link.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">form_secret: &lt;PRIVATE STRING&gt;
 </code></pre>
@@ -7648,6 +7664,8 @@ controls the behaviour of individual workers in isolation.</li>
 HTTP requests from workers.</p>
 <p>The default, this value is omitted (equivalently <code>null</code>), which means that
 traffic between the workers and the main process is not authenticated.</p>
+<p>Replacing an existing <code>worker_replication_secret</code> with a new one will break
+communication with all workers that have not yet updated their secret.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot;
 </code></pre>

develop/searchindex.js

@@ -1 +1 @@
-Object.assign(window.search, {"doc_urls":["welcome_and_overview.html#introduction","welcome_and_overview.html#installing-and-using-synapse","welcome_and_overview.html#developing-on-synapse","welcome_and_overview.html#reporting-a-security-vulnerability","setup/installation.html#installation-instructions","setup/installation.html#choosing-your-server-name","setup/installation.html#installing-synapse","setup/installation.html#prebuilt-packages","setup/installation.html#installing-as-a-python-module-from-pypi","setup/installation.html#setting-up-synapse","setup/installation.html#using-postgresql","setup/installation.html#tls-certificates","setup/installation.html#client-well-known-uri","setup/installation.html#email","setup/installation.html#registering-a-user","setup/installation.html#setting-up-a-turn-server","setup/installation.html#url-previews","setup/installation.html#backups","setup/installation.html#troubleshooting-installation","postgres.html#using-postgres","postgres.html#install-postgres-client-libraries","postgres.html#set-up-database","postgres.html#synapse-config","postgres.html#backups","postgres.html#tuning-postgres","postgres.html#porting-from-sqlite","postgres.html#overview","postgres.html#using-the-port-script","postgres.html#troubleshooting","postgres.html#alternative-auth-methods","postgres.html#fixing-incorrect-collate-or-ctype","reverse_proxy.html#using-a-reverse-proxy-with-synapse","reverse_proxy.html#homeserver-configuration","reverse_proxy.html#reverse-proxy-configuration-examples","reverse_proxy.html#nginx","reverse_proxy.html#caddy-v2","reverse_proxy.html#apache","reverse_proxy.html#haproxy","reverse_proxy.html#relayd","reverse_proxy.html#health-check-endpoint","reverse_proxy.html#synapse-administration-endpoints","setup/forward_proxy.html#using-a-forward-proxy-with-synapse","setup/forward_proxy.html#configure","setup/forward_proxy.html#connection-types","setup/forward_proxy.html#troubleshooting","turn-howto.html#overview","turn-howto.html#requirements","turn-howto.html#synapse-setup","turn-howto.html#troubleshooting","setup/turn/coturn.html#coturn-turn-server","setup/turn/coturn.html#coturn-setup","setup/turn/coturn.html#initial-installation","setup/turn/coturn.html#configuration","setup/turn/eturnal.html#eturnal-turn-server","setup/turn/eturnal.html#eturnal-setup","setup/turn/eturnal.html#initial-installation","setup/turn/eturnal.html#configuration","setup/turn/eturnal.html#eturnalctl-opterations-script","delegate.html#delegation-of-incoming-federation-traffic","delegate.html#well-known-delegation","delegate.html#external-server","delegate.html#serving-a-well-knownmatrixserver-file-with-synapse","delegate.html#srv-dns-record-delegation","delegate.html#delegation-faq","delegate.html#when-do-i-need-delegation","delegate.html#should-i-use-a-reverse-proxy-for-federation-traffic","upgrade.html#upgrading-synapse","upgrade.html#rolling-back-to-older-versions","upgrade.html#upgrading-from-a-very-old-version","upgrade.html#upgrading-to-v11220","upgrade.html#dropping-support-for-postgresql-11-and-12","upgrade.html#upgrading-to-v11200","upgrade.html#removal-of-experimental-msc3886-feature","upgrade.html#authenticated-media-is-now-enforced-by-default","upgrade.html#upgrading-to-v11190","upgrade.html#minimum-supported-python-version","upgrade.html#upgrading-to-v11110","upgrade.html#new-worker-endpoints-for-authenticated-client-and-federation-media","upgrade.html#upgrading-to-v11060","upgrade.html#minimum-supported-rust-version","upgrade.html#upgrading-to-v11000","upgrade.html#minimum-supported-rust-version-1","upgrade.html#upgrading-to-v1930","upgrade.html#minimum-supported-rust-version-2","upgrade.html#upgrading-to-v1900","upgrade.html#app-service-query-parameter-authorization-is-now-a-configuration-option","upgrade.html#upgrading-to-v1890","upgrade.html#removal-of-unspecced-user-property-for-register","upgrade.html#upgrading-to-v1880","upgrade.html#minimum-supported-python-version-1","upgrade.html#removal-of-worker_replication_-settings","upgrade.html#upgrading-to-v1860","upgrade.html#minimum-supported-rust-version-3","upgrade.html#upgrading-to-v1850","upgrade.html#application-service-registration-with-user-property-deprecation","upgrade.html#upgrading-to-v1840","upgrade.html#deprecation-of-worker_replication_-configuration-settings","upgrade.html#example-change","upgrade.html#upgrading-to-v1810","upgrade.html#application-service-path--authentication-deprecations","upgrade.html#upgrading-to-v1800","upgrade.html#reporting-events-error-code-change","upgrade.html#upgrading-to-v1790","upgrade.html#the-on_threepid_bind-module-callback-method-has-been-deprecated","upgrade.html#upgrading-to-v1780","upgrade.html#deprecate-the-_synapseadminv1mediadelete-admin-api","upgrade.html#upgrading-to-v1760","upgrade.html#faster-joins-are-enabled-by-default","upgrade.html#changes-to-the-account-data-replication-streams","upgrade.html#minimum-version-of-poetry-is-now-132","upgrade.html#upgrading-to-v1740","upgraLine truncated
+Object.assign(window.search, {"doc_urls":["welcome_and_overview.html#introduction","welcome_and_overview.html#installing-and-using-synapse","welcome_and_overview.html#developing-on-synapse","welcome_and_overview.html#reporting-a-security-vulnerability","setup/installation.html#installation-instructions","setup/installation.html#choosing-your-server-name","setup/installation.html#installing-synapse","setup/installation.html#prebuilt-packages","setup/installation.html#installing-as-a-python-module-from-pypi","setup/installation.html#setting-up-synapse","setup/installation.html#using-postgresql","setup/installation.html#tls-certificates","setup/installation.html#client-well-known-uri","setup/installation.html#email","setup/installation.html#registering-a-user","setup/installation.html#setting-up-a-turn-server","setup/installation.html#url-previews","setup/installation.html#backups","setup/installation.html#troubleshooting-installation","postgres.html#using-postgres","postgres.html#install-postgres-client-libraries","postgres.html#set-up-database","postgres.html#synapse-config","postgres.html#backups","postgres.html#tuning-postgres","postgres.html#porting-from-sqlite","postgres.html#overview","postgres.html#using-the-port-script","postgres.html#troubleshooting","postgres.html#alternative-auth-methods","postgres.html#fixing-incorrect-collate-or-ctype","reverse_proxy.html#using-a-reverse-proxy-with-synapse","reverse_proxy.html#homeserver-configuration","reverse_proxy.html#reverse-proxy-configuration-examples","reverse_proxy.html#nginx","reverse_proxy.html#caddy-v2","reverse_proxy.html#apache","reverse_proxy.html#haproxy","reverse_proxy.html#relayd","reverse_proxy.html#health-check-endpoint","reverse_proxy.html#synapse-administration-endpoints","setup/forward_proxy.html#using-a-forward-proxy-with-synapse","setup/forward_proxy.html#configure","setup/forward_proxy.html#connection-types","setup/forward_proxy.html#troubleshooting","turn-howto.html#overview","turn-howto.html#requirements","turn-howto.html#synapse-setup","turn-howto.html#troubleshooting","setup/turn/coturn.html#coturn-turn-server","setup/turn/coturn.html#coturn-setup","setup/turn/coturn.html#initial-installation","setup/turn/coturn.html#configuration","setup/turn/eturnal.html#eturnal-turn-server","setup/turn/eturnal.html#eturnal-setup","setup/turn/eturnal.html#initial-installation","setup/turn/eturnal.html#configuration","setup/turn/eturnal.html#eturnalctl-opterations-script","delegate.html#delegation-of-incoming-federation-traffic","delegate.html#well-known-delegation","delegate.html#external-server","delegate.html#serving-a-well-knownmatrixserver-file-with-synapse","delegate.html#srv-dns-record-delegation","delegate.html#delegation-faq","delegate.html#when-do-i-need-delegation","delegate.html#should-i-use-a-reverse-proxy-for-federation-traffic","upgrade.html#upgrading-synapse","upgrade.html#rolling-back-to-older-versions","upgrade.html#upgrading-from-a-very-old-version","upgrade.html#upgrading-to-v11220","upgrade.html#dropping-support-for-postgresql-11-and-12","upgrade.html#upgrading-to-v11200","upgrade.html#removal-of-experimental-msc3886-feature","upgrade.html#authenticated-media-is-now-enforced-by-default","upgrade.html#upgrading-to-v11190","upgrade.html#minimum-supported-python-version","upgrade.html#upgrading-to-v11110","upgrade.html#new-worker-endpoints-for-authenticated-client-and-federation-media","upgrade.html#upgrading-to-v11060","upgrade.html#minimum-supported-rust-version","upgrade.html#upgrading-to-v11000","upgrade.html#minimum-supported-rust-version-1","upgrade.html#upgrading-to-v1930","upgrade.html#minimum-supported-rust-version-2","upgrade.html#upgrading-to-v1900","upgrade.html#app-service-query-parameter-authorization-is-now-a-configuration-option","upgrade.html#upgrading-to-v1890","upgrade.html#removal-of-unspecced-user-property-for-register","upgrade.html#upgrading-to-v1880","upgrade.html#minimum-supported-python-version-1","upgrade.html#removal-of-worker_replication_-settings","upgrade.html#upgrading-to-v1860","upgrade.html#minimum-supported-rust-version-3","upgrade.html#upgrading-to-v1850","upgrade.html#application-service-registration-with-user-property-deprecation","upgrade.html#upgrading-to-v1840","upgrade.html#deprecation-of-worker_replication_-configuration-settings","upgrade.html#example-change","upgrade.html#upgrading-to-v1810","upgrade.html#application-service-path--authentication-deprecations","upgrade.html#upgrading-to-v1800","upgrade.html#reporting-events-error-code-change","upgrade.html#upgrading-to-v1790","upgrade.html#the-on_threepid_bind-module-callback-method-has-been-deprecated","upgrade.html#upgrading-to-v1780","upgrade.html#deprecate-the-_synapseadminv1mediadelete-admin-api","upgrade.html#upgrading-to-v1760","upgrade.html#faster-joins-are-enabled-by-default","upgrade.html#changes-to-the-account-data-replication-streams","upgrade.html#minimum-version-of-poetry-is-now-132","upgrade.html#upgrading-to-v1740","upgraLine truncated

develop/searchindex.json

@@ -1 +1 @@
-{"doc_urls":["welcome_and_overview.html#introduction","welcome_and_overview.html#installing-and-using-synapse","welcome_and_overview.html#developing-on-synapse","welcome_and_overview.html#reporting-a-security-vulnerability","setup/installation.html#installation-instructions","setup/installation.html#choosing-your-server-name","setup/installation.html#installing-synapse","setup/installation.html#prebuilt-packages","setup/installation.html#installing-as-a-python-module-from-pypi","setup/installation.html#setting-up-synapse","setup/installation.html#using-postgresql","setup/installation.html#tls-certificates","setup/installation.html#client-well-known-uri","setup/installation.html#email","setup/installation.html#registering-a-user","setup/installation.html#setting-up-a-turn-server","setup/installation.html#url-previews","setup/installation.html#backups","setup/installation.html#troubleshooting-installation","postgres.html#using-postgres","postgres.html#install-postgres-client-libraries","postgres.html#set-up-database","postgres.html#synapse-config","postgres.html#backups","postgres.html#tuning-postgres","postgres.html#porting-from-sqlite","postgres.html#overview","postgres.html#using-the-port-script","postgres.html#troubleshooting","postgres.html#alternative-auth-methods","postgres.html#fixing-incorrect-collate-or-ctype","reverse_proxy.html#using-a-reverse-proxy-with-synapse","reverse_proxy.html#homeserver-configuration","reverse_proxy.html#reverse-proxy-configuration-examples","reverse_proxy.html#nginx","reverse_proxy.html#caddy-v2","reverse_proxy.html#apache","reverse_proxy.html#haproxy","reverse_proxy.html#relayd","reverse_proxy.html#health-check-endpoint","reverse_proxy.html#synapse-administration-endpoints","setup/forward_proxy.html#using-a-forward-proxy-with-synapse","setup/forward_proxy.html#configure","setup/forward_proxy.html#connection-types","setup/forward_proxy.html#troubleshooting","turn-howto.html#overview","turn-howto.html#requirements","turn-howto.html#synapse-setup","turn-howto.html#troubleshooting","setup/turn/coturn.html#coturn-turn-server","setup/turn/coturn.html#coturn-setup","setup/turn/coturn.html#initial-installation","setup/turn/coturn.html#configuration","setup/turn/eturnal.html#eturnal-turn-server","setup/turn/eturnal.html#eturnal-setup","setup/turn/eturnal.html#initial-installation","setup/turn/eturnal.html#configuration","setup/turn/eturnal.html#eturnalctl-opterations-script","delegate.html#delegation-of-incoming-federation-traffic","delegate.html#well-known-delegation","delegate.html#external-server","delegate.html#serving-a-well-knownmatrixserver-file-with-synapse","delegate.html#srv-dns-record-delegation","delegate.html#delegation-faq","delegate.html#when-do-i-need-delegation","delegate.html#should-i-use-a-reverse-proxy-for-federation-traffic","upgrade.html#upgrading-synapse","upgrade.html#rolling-back-to-older-versions","upgrade.html#upgrading-from-a-very-old-version","upgrade.html#upgrading-to-v11220","upgrade.html#dropping-support-for-postgresql-11-and-12","upgrade.html#upgrading-to-v11200","upgrade.html#removal-of-experimental-msc3886-feature","upgrade.html#authenticated-media-is-now-enforced-by-default","upgrade.html#upgrading-to-v11190","upgrade.html#minimum-supported-python-version","upgrade.html#upgrading-to-v11110","upgrade.html#new-worker-endpoints-for-authenticated-client-and-federation-media","upgrade.html#upgrading-to-v11060","upgrade.html#minimum-supported-rust-version","upgrade.html#upgrading-to-v11000","upgrade.html#minimum-supported-rust-version-1","upgrade.html#upgrading-to-v1930","upgrade.html#minimum-supported-rust-version-2","upgrade.html#upgrading-to-v1900","upgrade.html#app-service-query-parameter-authorization-is-now-a-configuration-option","upgrade.html#upgrading-to-v1890","upgrade.html#removal-of-unspecced-user-property-for-register","upgrade.html#upgrading-to-v1880","upgrade.html#minimum-supported-python-version-1","upgrade.html#removal-of-worker_replication_-settings","upgrade.html#upgrading-to-v1860","upgrade.html#minimum-supported-rust-version-3","upgrade.html#upgrading-to-v1850","upgrade.html#application-service-registration-with-user-property-deprecation","upgrade.html#upgrading-to-v1840","upgrade.html#deprecation-of-worker_replication_-configuration-settings","upgrade.html#example-change","upgrade.html#upgrading-to-v1810","upgrade.html#application-service-path--authentication-deprecations","upgrade.html#upgrading-to-v1800","upgrade.html#reporting-events-error-code-change","upgrade.html#upgrading-to-v1790","upgrade.html#the-on_threepid_bind-module-callback-method-has-been-deprecated","upgrade.html#upgrading-to-v1780","upgrade.html#deprecate-the-_synapseadminv1mediadelete-admin-api","upgrade.html#upgrading-to-v1760","upgrade.html#faster-joins-are-enabled-by-default","upgrade.html#changes-to-the-account-data-replication-streams","upgrade.html#minimum-version-of-poetry-is-now-132","upgrade.html#upgrading-to-v1740","upgrade.html#unicode-support-in-usLine truncated
+{"doc_urls":["welcome_and_overview.html#introduction","welcome_and_overview.html#installing-and-using-synapse","welcome_and_overview.html#developing-on-synapse","welcome_and_overview.html#reporting-a-security-vulnerability","setup/installation.html#installation-instructions","setup/installation.html#choosing-your-server-name","setup/installation.html#installing-synapse","setup/installation.html#prebuilt-packages","setup/installation.html#installing-as-a-python-module-from-pypi","setup/installation.html#setting-up-synapse","setup/installation.html#using-postgresql","setup/installation.html#tls-certificates","setup/installation.html#client-well-known-uri","setup/installation.html#email","setup/installation.html#registering-a-user","setup/installation.html#setting-up-a-turn-server","setup/installation.html#url-previews","setup/installation.html#backups","setup/installation.html#troubleshooting-installation","postgres.html#using-postgres","postgres.html#install-postgres-client-libraries","postgres.html#set-up-database","postgres.html#synapse-config","postgres.html#backups","postgres.html#tuning-postgres","postgres.html#porting-from-sqlite","postgres.html#overview","postgres.html#using-the-port-script","postgres.html#troubleshooting","postgres.html#alternative-auth-methods","postgres.html#fixing-incorrect-collate-or-ctype","reverse_proxy.html#using-a-reverse-proxy-with-synapse","reverse_proxy.html#homeserver-configuration","reverse_proxy.html#reverse-proxy-configuration-examples","reverse_proxy.html#nginx","reverse_proxy.html#caddy-v2","reverse_proxy.html#apache","reverse_proxy.html#haproxy","reverse_proxy.html#relayd","reverse_proxy.html#health-check-endpoint","reverse_proxy.html#synapse-administration-endpoints","setup/forward_proxy.html#using-a-forward-proxy-with-synapse","setup/forward_proxy.html#configure","setup/forward_proxy.html#connection-types","setup/forward_proxy.html#troubleshooting","turn-howto.html#overview","turn-howto.html#requirements","turn-howto.html#synapse-setup","turn-howto.html#troubleshooting","setup/turn/coturn.html#coturn-turn-server","setup/turn/coturn.html#coturn-setup","setup/turn/coturn.html#initial-installation","setup/turn/coturn.html#configuration","setup/turn/eturnal.html#eturnal-turn-server","setup/turn/eturnal.html#eturnal-setup","setup/turn/eturnal.html#initial-installation","setup/turn/eturnal.html#configuration","setup/turn/eturnal.html#eturnalctl-opterations-script","delegate.html#delegation-of-incoming-federation-traffic","delegate.html#well-known-delegation","delegate.html#external-server","delegate.html#serving-a-well-knownmatrixserver-file-with-synapse","delegate.html#srv-dns-record-delegation","delegate.html#delegation-faq","delegate.html#when-do-i-need-delegation","delegate.html#should-i-use-a-reverse-proxy-for-federation-traffic","upgrade.html#upgrading-synapse","upgrade.html#rolling-back-to-older-versions","upgrade.html#upgrading-from-a-very-old-version","upgrade.html#upgrading-to-v11220","upgrade.html#dropping-support-for-postgresql-11-and-12","upgrade.html#upgrading-to-v11200","upgrade.html#removal-of-experimental-msc3886-feature","upgrade.html#authenticated-media-is-now-enforced-by-default","upgrade.html#upgrading-to-v11190","upgrade.html#minimum-supported-python-version","upgrade.html#upgrading-to-v11110","upgrade.html#new-worker-endpoints-for-authenticated-client-and-federation-media","upgrade.html#upgrading-to-v11060","upgrade.html#minimum-supported-rust-version","upgrade.html#upgrading-to-v11000","upgrade.html#minimum-supported-rust-version-1","upgrade.html#upgrading-to-v1930","upgrade.html#minimum-supported-rust-version-2","upgrade.html#upgrading-to-v1900","upgrade.html#app-service-query-parameter-authorization-is-now-a-configuration-option","upgrade.html#upgrading-to-v1890","upgrade.html#removal-of-unspecced-user-property-for-register","upgrade.html#upgrading-to-v1880","upgrade.html#minimum-supported-python-version-1","upgrade.html#removal-of-worker_replication_-settings","upgrade.html#upgrading-to-v1860","upgrade.html#minimum-supported-rust-version-3","upgrade.html#upgrading-to-v1850","upgrade.html#application-service-registration-with-user-property-deprecation","upgrade.html#upgrading-to-v1840","upgrade.html#deprecation-of-worker_replication_-configuration-settings","upgrade.html#example-change","upgrade.html#upgrading-to-v1810","upgrade.html#application-service-path--authentication-deprecations","upgrade.html#upgrading-to-v1800","upgrade.html#reporting-events-error-code-change","upgrade.html#upgrading-to-v1790","upgrade.html#the-on_threepid_bind-module-callback-method-has-been-deprecated","upgrade.html#upgrading-to-v1780","upgrade.html#deprecate-the-_synapseadminv1mediadelete-admin-api","upgrade.html#upgrading-to-v1760","upgrade.html#faster-joins-are-enabled-by-default","upgrade.html#changes-to-the-account-data-replication-streams","upgrade.html#minimum-version-of-poetry-is-now-132","upgrade.html#upgrading-to-v1740","upgrade.html#unicode-support-in-usLine truncated

develop/usage/configuration/config_documentation.html

@@ -2324,6 +2324,14 @@ set.</p>
 <p>This is primarily intended for use with the <code>register_new_matrix_user</code> script
 (see <a href="../../setup/installation.html#registering-a-user">Registering a user</a>);
 however, the interface is <a href="../../admin_api/register_api.html">documented</a>.</p>
+<p>Replacing an existing <code>registration_shared_secret</code> with a new one requires users
+of the <a href="../../admin_api/register_api.html">Shared-Secret Registration API</a> to
+start using the new secret for requesting any further one-time nonces.</p>
+<blockquote>
+<p>⚠️ <strong>Warning</strong> – The additional consequences of replacing
+<a href="#macaroon_secret_key"><code>macaroon_secret_key</code></a> will apply in case it delegates
+to <code>registration_shared_secret</code>.</p>
+</blockquote>
 <p>See also <a href="#registration_shared_secret_path"><code>registration_shared_secret_path</code></a>.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">registration_shared_secret: &lt;PRIVATE STRING&gt;
@@ -2754,6 +2762,12 @@ access tokens via a query parameter.</p>
 </ul>
 <p>If none is specified, the <code>registration_shared_secret</code> is used, if one is given;
 otherwise, a secret key is derived from the signing key.</p>
+<blockquote>
+<p>⚠️ <strong>Warning</strong> – Replacing an existing <code>macaroon_secret_key</code> with a new one
+will lead to invalidation of access tokens for all guest users. It will also
+break unsubscribe links in emails sent before the change. An unlucky user
+might encounter a broken SSO login flow and would have to start again.</p>
+</blockquote>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">macaroon_secret_key: &lt;PRIVATE STRING&gt;
 </code></pre>
@@ -2772,6 +2786,8 @@ Synapse reads the secret key from the given file once at startup.</p>
 <p>A secret which is used to calculate HMACs for form values, to stop
 falsification of values. Must be specified for the User Consent
 forms to work.</p>
+<p>Replacing an existing <code>form_secret</code> with a new one might break the user consent
+page for an unlucky user and require them to reopen the page from a new link.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">form_secret: &lt;PRIVATE STRING&gt;
 </code></pre>
@@ -3961,6 +3977,8 @@ controls the behaviour of individual workers in isolation.</li>
 HTTP requests from workers.</p>
 <p>The default, this value is omitted (equivalently <code>null</code>), which means that
 traffic between the workers and the main process is not authenticated.</p>
+<p>Replacing an existing <code>worker_replication_secret</code> with a new one will break
+communication with all workers that have not yet updated their secret.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot;
 </code></pre>