This documentation is out of date!

This documentation site is for the versions of matrix-authentication-service maintained by the Matrix.org Foundation (github.com/matrix-org/matrix-authentication-service), available under the Apache 2.0 licence.

Since version 0.12.0, matrix-authentication-service is now maintained by Element under a new licence (github.com/element-hq/matrix-authentication-service).

If you are interested in the documentation for a later version of matrix-authentication-service, please refer to https://element-hq.github.io/matrix-authentication-service/.

Homeserver configuration

The matrix-authentication-service is designed to be run alongside a Matrix homeserver. It currently only supports 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 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, 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
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 command.

Configure the connection to the homeserver

In the matrix section of the configuration file, add the following properties:

  • homeserver: corresponds to the server_name in the Synapse configuration file
  • secret: a shared secret the service will use to call the homeserver admin API
  • endpoint: the URL to which the homeserver is accessible from the service
matrix:
  homeserver: localhost:8008
  secret: "AnotherRandomSecret"
  endpoint: "http://localhost:8008"

Configure the homeserver to delegate authentication to the service

Set up the delegated authentication feature in the Synapse configuration in the experimental_features section:

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
    account_management_url: "http://localhost:8080/account"

Set up the compatibility layer

The service exposes a compatibility layer to allow legacy clients to authenticate using the service. This works by exposing a few Matrix endpoints that should be proxied to the service.

The following Matrix Client-Server API endpoints need to be handled by the authentication service:

See the reverse proxy configuration guide for more information.