From bd964e661370e5ad1240e3ccf5aa384279787507 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Zelina?= Date: Tue, 26 Aug 2025 13:37:39 +0200 Subject: [PATCH] Updated homeserver configuration documentation to new configuration option --- docs/setup/homeserver.md | 66 ++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 43 deletions(-) diff --git a/docs/setup/homeserver.md b/docs/setup/homeserver.md index 614d4b190..bee1b73ec 100644 --- a/docs/setup/homeserver.md +++ b/docs/setup/homeserver.md @@ -4,22 +4,7 @@ The `matrix-authentication-service` is designed to be run alongside a Matrix hom It currently only supports [Synapse](https://github.com/element-hq/synapse) through the experimental OAuth delegation feature. The authentication service needs to be able to call the Synapse admin API to provision users through a shared secret, and Synapse needs to be able to call the service to verify access tokens using the OAuth 2.0 token introspection endpoint. -## Provision a client for the Homeserver to use - -In the [`clients`](../reference/configuration.md#clients) section of the configuration file, add a new client with the following properties: - - - `client_id`: a unique identifier for the client. It must be a valid [ULID](https://github.com/ulid/spec), and it happens that `0000000000000000000SYNAPSE` is a valid ULID. - - `client_auth_method`: set to `client_secret_basic`. Other methods are possible, but this is the easiest to set up. - - `client_secret`: a shared secret used for the homeserver to authenticate - -```yaml -clients: - - client_id: 0000000000000000000SYNAPSE - client_auth_method: client_secret_basic - client_secret: "SomeRandomSecret" -``` - -**Don't forget to sync the configuration file** with the database after adding the client, using the [`config sync`](../reference/cli/config.md#config-sync---prune---dry-run) command. +> Note: This documentation applies to Synapse v1.136.0 and higher. For older Synapse versions, refer to docs for [v0.16](https://github.com/element-hq/matrix-authentication-service/blob/release/v0.20/docs/setup/homeserver.md) ## Configure the connection to the homeserver @@ -32,43 +17,38 @@ In the [`matrix`](../reference/configuration.md#matrix) section of the configura ```yaml matrix: homeserver: localhost:8008 - secret: "AnotherRandomSecret" + secret: "SomeRandomSecret" endpoint: "http://localhost:8008" ``` +**Don't forget to sync the configuration file** with the database after configuring homeserver connection, using the [`config sync`](../reference/cli/config.md#config-sync---prune---dry-run) command. + ## Configure the homeserver to delegate authentication to the service -Set up the delegated authentication feature in the Synapse configuration in the `experimental_features` section: +Set up the delegated authentication feature in the Synapse configuration: + +```yaml +matrix_authentication_service: + # Enable the MAS integration + enabled: true + # The base URL where Synapse will contact MAS + endpoint: http://localhost:8080 + # The shared secret used to authenticate MAS requests, must be the same as `matrix.secret` in the MAS configuration + # See https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#matrix + secret: "SomeRandomSecret" +``` + +## Optional: Enable QR code login + +To enable QR code login you need to enable MSC 4108 in the Synapse configuration in the `experimental_features` section: ```yaml experimental_features: - msc3861: - enabled: true - - # Synapse will call `{issuer}/.well-known/openid-configuration` to get the OIDC configuration - issuer: http://localhost:8080/ - - # Matches the `client_id` in the auth service config - client_id: 0000000000000000000SYNAPSE - # Matches the `client_auth_method` in the auth service config - client_auth_method: client_secret_basic - # Matches the `client_secret` in the auth service config - client_secret: "SomeRandomSecret" - - # Matches the `matrix.secret` in the auth service config - admin_token: "AnotherRandomSecret" - - # URL to advertise to clients where users can self-manage their account - # Defaults to the URL advertised by MAS, e.g. `https://{public_mas_domain}/account/` - #account_management_url: "http://localhost:8080/account/" - - # URL which Synapse will use to introspect access tokens - # Defaults to the URL advertised by MAS, e.g. `https://{public_mas_domain}/oauth2/introspect` - # This is useful to override if Synapse has a way to call the auth service's - # introspection endpoint directly, skipping intermediate reverse proxies - #introspection_endpoint: "http://localhost:8080/oauth2/introspect" + msc4108_enabled: true ``` +> Note: There is a [known bug](https://github.com/element-hq/synapse/issues/18808) that prevents enabling MSC 4108 in Synapse v1.136.0 when MAS is configured as described above. Either use the [older method of configuring MAS on Synapse](https://github.com/element-hq/matrix-authentication-service/blob/release/v0.20/docs/setup/homeserver.md), or upgrade to v1.137.0 + ## Set up the compatibility layer The service exposes a compatibility layer to allow legacy clients to authenticate using the service.