Using the service

Running

Once the configuration is done, one should run the database migrations (database schema upgrade, also for setup) by running

mas-cli database migrate

The server can then be started by running

mas-cli server

Sep 24 14:42:42.743  INFO mas_cli::server: Starting task scheduler
Sep 24 14:42:42.743  INFO mas_core::templates: Loading builtin templates
Sep 24 14:42:42.752  INFO mas_cli::server: Listening on http://0.0.0.0:8080

The server should now be accessible through http://localhost:8080/.

Note: when running with Docker, the port used by the server should be exposed with the -p flag:

docker run --rm \
  -v `pwd`/config.yaml:/config.yaml \
  -p 8080:8080 \
  ghcr.io/matrix-org/matrix-authentication-service:main \
  server

Registering, logging in and out

Through the interface, users are able to create an account by clicking the Register button on the top right (or going to /register). They can then end their session by clicking the Sign out button and sign back in.

Playing around with the playground

The OpenID Foundation hosts a OpenID Connect Playground where one can test logging in through an OIDC provider: https://openidconnect.net/

Step 1: Add the client to the server config

Add the following section to the server configuration file config.yaml:

clients:
  # The client ID must be a valid ULID
  - client_id: 000000000000OIDCPLAYGROUND
    client_secret: verysecret
    redirect_uris:
      - "https://openidconnect.net/callback"

Sync the configuration with the database:

mas-cli config sync

Step 2: Change the playground configuration

Navigate to the playground
Click on "Configuration"
Server template: Custom
Paste the discovery document URL found on the service homepage (e.g. http://localhost:8080/.well-known/openid-configuration)
Click "Use discovery document" ; it should fill out the authorization, token and token keys endpoints
Set the OIDC Client ID to 000000000000OIDCPLAYGROUND and the Client Secret to verysecret (must match the ones in the configuration)
Click "Save"

Step 3: Run the OpenID Connect flow

Start the flow by clicking the "Start" button. It should redirect the browser to the authentication service. If a user is already logged in, it should redirect back to the playground immediately.

Follow the flow to see the code exchange happen. Note that the last step only works if the service is accessible through the internet.

Matrix Authentication Service