From f24d94c6f5ae9d282ca0c86da46c64b6b1cfd1ba Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 23 Apr 2025 18:52:34 +0200 Subject: [PATCH] docs: stop talking about the .well-known/matrix/client changes These were relevant on an old version of the specs, and just confuses people. --- docs/SUMMARY.md | 1 - docs/setup/README.md | 34 +--------------------------------- docs/setup/migration.md | 4 ---- docs/setup/well-known.md | 23 ----------------------- 4 files changed, 1 insertion(+), 61 deletions(-) delete mode 100644 docs/setup/well-known.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index de087925c..0b623e7b2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -12,7 +12,6 @@ - [Database setup](./setup/database.md) - [Homeserver configuration](./setup/homeserver.md) - [Configuring a reverse proxy](./setup/reverse-proxy.md) -- [Configuring .well-known](./setup/well-known.md) - [Configure an upstream SSO provider](./setup/sso.md) - [Running the service](./setup/running.md) - [Migrating an existing homeserver](./setup/migration.md) diff --git a/docs/setup/README.md b/docs/setup/README.md index 6ff08d2bf..54b8ae8b4 100644 --- a/docs/setup/README.md +++ b/docs/setup/README.md @@ -11,43 +11,11 @@ The authentication service becomes the source of truth for user accounts and acc At time of writing, the authentication service is meant to be run on a standalone domain name (e.g. `auth.example.com`), and the homeserver on another (e.g. `matrix.example.com`). This domain will be user-facing as part of the authentication flow. -When a client initiates an authentication flow, it will discover the authentication service through the deployment `.well-known/matrix/client` endpoint. -This file will refer to an `issuer`, which is the canonical name of the authentication service instance. -Out of that issuer, it will discover the rest of the endpoints by calling the `[issuer]/.well-known/openid-configuration` endpoint. -By default, the `issuer` will match the root domain where the service is deployed (e.g. `https://auth.example.com/`), but it can be configured to be different. - An example setup could look like this: - The deployment domain is `example.com`, so Matrix IDs look like `@user:example.com` - - The issuer chosen is `https://auth.example.com/` - - The homeserver is deployed on `matrix.example.com` - The authentication service is deployed on `auth.example.com` - - Calling `https://example.com/.well-known/matrix/client` returns the following JSON: - - ```json - { - "m.homeserver": { - "base_url": "https://matrix.example.com" - }, - "org.matrix.msc2965.authentication": { - "issuer": "https://auth.example.com/", - "account": "https://auth.example.com/account" - } - } - ``` - - - Calling `https://auth.example.com/.well-known/openid-configuration` returns a JSON document similar to the following: - - ```json - { - "issuer": "https://auth.example.com/", - "authorization_endpoint": "https://auth.example.com/authorize", - "token_endpoint": "https://auth.example.com/oauth2/token", - "jwks_uri": "https://auth.example.com/oauth2/keys.json", - "registration_endpoint": "https://auth.example.com/oauth2/registration", - "//": "..." - } - ``` + - The homeserver is deployed on `matrix.example.com` With the installation planned, it is time to go through the installation and configuration process. The first section focuses on [installing the service](./installation.md). diff --git a/docs/setup/migration.md b/docs/setup/migration.md index b5f93d534..69e04311f 100644 --- a/docs/setup/migration.md +++ b/docs/setup/migration.md @@ -203,7 +203,3 @@ Start up the homeserver again with the new configuration. ### Start up MAS Start up MAS. - -### Update or serve the .well-known - -The `.well-known/matrix/client` needs to be served as described [here](./well-known.md). diff --git a/docs/setup/well-known.md b/docs/setup/well-known.md deleted file mode 100644 index 65b2990b4..000000000 --- a/docs/setup/well-known.md +++ /dev/null @@ -1,23 +0,0 @@ -# .well-known configuration - -A `.well-known/matrix/client` file is required to be served to allow clients to discover the authentication service. - -If no `.well-known/matrix/client` file is served currently then this will need to be enabled. - -If the homeserver is Synapse and serving this file already then the correct values will already be included when the homeserver is [configured to use MAS](./homeserver.md). - -If the .well-known is hosted elsewhere then `org.matrix.msc2965.authentication` entries need to be included similar to the following: - -```json -{ - "m.homeserver": { - "base_url": "https://matrix.example.com" - }, - "org.matrix.msc2965.authentication": { - "issuer": "https://example.com/", - "account": "https://auth.example.com/account" - } -} -``` - -For more context on what the correct values are, see [here](./).