Skip to content

Update homeserver configuration documentation to new matrix_authentication_service configuration option #4948

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update homeserver configuration documentation to new matrix_authentication_service configuration option #4948

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 23 additions & 43 deletions docs/setup/homeserver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Expand Down