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/.

Running the service

To fully function, the service needs to run two main components:

  • An HTTP server
  • A background worker

By default, the mas-cli server command will start both components. It is possible to only run the HTTP server by setting the --no-worker option, and run a background worker with the mas-cli worker command.

Both components are stateless, and can be scaled horizontally by running multiple instances of each.

Runtime requirements

Other than the binary, the service needs a few files to run:

  • The templates, referenced by the templates.path configuration option
  • The compiled policy, referenced by the policy.path configuration option
  • The frontend assets, referenced by the path option of the assets resource in the http.listeners configuration section
  • The frontend manifest file, referenced by tge templates.assets_manifest configuration option

Be sure to check the installation instructions for more information on how to get these files, and make sure the configuration file is updated accordingly.

If you are using the docker image, everything is already included in the image at the right place, so in most cases you don't need to do anything.

If you are using the pre-built binaries, those files are shipped alongside them in the share directory. The default configuration will look for them from the current working directory, meaning that you don't have to adjust the paths, as long as you are running the service from the parent directory of the share directory.

Configure the HTTP server

The service can be configured to have multiple HTTP listeners, serving different resources. See the http.listeners configuration section for more information.

The service needs to be aware of the public URL it is served on, regardless of the HTTP listeners configuration. This is done using the http.public_base configuration option. By default, the OIDC issuer advertised by the /.well-known/openid-configuration endpoint will be the same as the public_base URL, but can be configured to be different.

Tweak the remaining configuration

A few configuration sections might still require some tweaking, including:

  • telemetry: to setup metrics, tracing and Sentry crash reporting
  • email: to setup email sending
  • password: to enable/disable password authentication
  • account: to configure what account management features are enabled
  • upstream_oauth: to configure upstream OAuth providers

Run the service

Once the configuration is done, the service can be started with the mas-cli server command:

mas-cli server

It is advised to run the service as a non-root user, using a tool like systemd to manage the service lifecycle.

Troubleshoot common issues

Once the service is running, it is possible to check its configuration using the mas-cli doctor command. This should help diagnose common issues with the service configuration and deployment.