Planning the installation

This part of the documentation goes through installing the service, the important parts of the configuration file, and how to run the service.

Before going through the installation, it is important to understand the different components of an OIDC-native Matrix homeserver, and how they interact with each other. It is meant to complement the homeserver, replacing the internal authentication mechanism with the authentication service.

Making a homeserver deployment OIDC-native radically shifts the authentication model: the homeserver is no longer responsible for managing user accounts and sessions. The authentication service becomes the source of truth for user accounts and access tokens, and the homeserver only verifies the validity of the tokens it receives through the service.

At time of writing, the authentication service is meant to be run on a standalone domain name (e.g. auth.example.com), and the homeserver on another (e.g. matrix.example.com). This domain will be user-facing as part of the authentication flow.

When a client initiates an authentication flow, it will discover the authentication service through the deployment .well-known/matrix/client endpoint. This file will refer to an issuer, which is the canonical name of the authentication service instance. Out of that issuer, it will discover the rest of the endpoints by calling the [issuer]/.well-known/openid-configuration endpoint. By default, the issuer will match the root domain where the service is deployed (e.g. https://auth.example.com/), but it can be configured to be different.

An example setup could look like this:

  • The deployment domain is example.com, so Matrix IDs look like @user:example.com

  • The issuer chosen is https://example.com/

  • The homeserver is deployed on matrix.example.com

  • The authentication service is deployed on auth.example.com

  • Calling https://example.com/.well-known/matrix/client returns the following JSON:

    {
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  },
  "org.matrix.msc2965.authentication": {
    "issuer": "https://example.com/",
    "account": "https://auth.example.com/account"
  }
}

  • Calling https://example.com/.well-known/openid-configuration returns a JSON document similar to the following:

    {
    "issuer": "https://example.com/",
    "authorization_endpoint": "https://auth.example.com/authorize",
    "token_endpoint": "https://auth.example.com/oauth2/token",
    "jwks_uri": "https://auth.example.com/oauth2/keys.json",
    "registration_endpoint": "https://auth.example.com/oauth2/registration",
    "//": "..."
}

With the installation planned, it is time to go through the installation and configuration process. The first section focuses on installing the service.