2 files changed, 20 insertions, 0 deletions
diff --git a/changelog.d/18138.doc b/changelog.d/18138.doc
new file mode 100644
index 0000000000..5f07cd2763
--- /dev/null
+++ b/changelog.d/18138.doc
@@ -0,0 +1 @@
+Document consequences of replacing secrets.
\ No newline at end of file
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 92ab6438c1..e3c06d5371 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -2592,6 +2592,14 @@ This is primarily intended for use with the `register_new_matrix_user` script
(see [Registering a user](../../setup/installation.md#registering-a-user));
however, the interface is [documented](../../admin_api/register_api.html).
+Replacing an existing `registration_shared_secret` with a new one requires users
+of the [Shared-Secret Registration API](../../admin_api/register_api.html) to
+start using the new secret for requesting any further one-time nonces.
+
+> ⚠️ **Warning** – The additional consequences of replacing
+> [`macaroon_secret_key`](#macaroon_secret_key) will apply in case it delegates
+> to `registration_shared_secret`.
+
See also [`registration_shared_secret_path`](#registration_shared_secret_path).
Example configuration:
@@ -3168,6 +3176,11 @@ A secret which is used to sign
If none is specified, the `registration_shared_secret` is used, if one is given;
otherwise, a secret key is derived from the signing key.
+> ⚠️ **Warning** – Replacing an existing `macaroon_secret_key` 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.
+
Example configuration:
```yaml
macaroon_secret_key: <PRIVATE STRING>
@@ -3195,6 +3208,9 @@ 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.
+Replacing an existing `form_secret` 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.
+
Example configuration:
```yaml
form_secret: <PRIVATE STRING>
@@ -4443,6 +4459,9 @@ HTTP requests from workers.
The default, this value is omitted (equivalently `null`), which means that
traffic between the workers and the main process is not authenticated.
+Replacing an existing `worker_replication_secret` with a new one will break
+communication with all workers that have not yet updated their secret.
+
Example configuration:
```yaml
worker_replication_secret: "secret_secret"
|
