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

Installation

Pre-built binaries

Pre-built binaries can be found attached on each release, for Linux on both x86_64 and aarch64 architectures.

Each archive contains:

  • the mas-cli binary
  • assets needed for running the service, including:
    • share/assets/: the built frontend assets
    • share/manifest.json: the manifest for the frontend assets
    • share/policy.wasm: the built OPA policies
    • share/templates/: the default templates
    • share/translations/: the default translations

The location of all these assets can be overridden in the configuration file.

Example shell commands to download and extract the mas-cli binary:

ARCH=x86_64 # or aarch64
OS=linux
VERSION=latest # or a specific version, like "v0.1.0"

# URL to the right archive
URL="https://github.com/matrix-org/matrix-authentication-service/releases/${VERSION}/download/mas-cli-${ARCH}-${OS}.tar.gz"

# Create a directory and extract the archive in it
mkdir -p /path/to/mas
curl -sL "$URL" | tar xzC /path/to/mas

# This should display the help message
/path/to/mas/mas-cli --help

Using the Docker image

A pre-built Docker image is available here: ghcr.io/matrix-org/matrix-authentication-service:latest

The latest tag is built using the latest release. The main tag is built from the main branch, and each commit on the main branch is also tagged with a stable sha-<commit sha> tag.

The image can also be built from the source:

  1. Get the source 
    git clone https://github.com/matrix-org/matrix-authentication-service.git
cd matrix-authentication-service
  2. Build the image 
    docker build -t mas .

Building from the source

Building from the source requires:

  1. Get the source 
    git clone https://github.com/matrix-org/matrix-authentication-service.git
cd matrix-authentication-service
  2. Build the frontend 
    cd frontend
npm ci
npm run build
cd ..
    This will produce a frontend/dist directory containing the built frontend assets. This folder, along with the frontend/dist/manifest.json file, can be relocated, as long as the configuration file is updated accordingly.
  3. Build the Open Policy Agent policies 
    cd policies
make
cd ..
    OR, if you don't have opa installed and want to build through the OPA docker image 
    cd policies
make DOCKER=1
cd ..
    This will produce a policies/policy.wasm file containing the built OPA policies. This file can be relocated, as long as the configuration file is updated accordingly.
  4. Compile the CLI 
    cargo build --release
  5. Grab the built binary 
    cp ./target/release/mas-cli ~/.local/bin # Copy the binary somewhere in $PATH
mas-cli --help # Should display the help message

Next steps

The service needs some configuration to work. This includes random, private keys and secrets. Follow the configuration guide to configure the service.