You've already forked authentication-service
mirror of
https://github.com/matrix-org/matrix-authentication-service.git
synced 2025-07-31 09:24:31 +03:00
docs: expand the setup documentation and configuration file reference
This commit is contained in:
Quentin Gliech
@ -1,4 +1,53 @@
|
||||
# Setup introduction
|
||||
# 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:
|
||||
|
||||
```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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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](./installation.md).
|
||||
|
||||
@ -69,6 +69,6 @@ mas-cli server --migrate
|
||||
Once the database is up, the remaining steps are to:
|
||||
|
||||
- [Set up the connection to the homeserver (recommended)](./homeserver.md)
|
||||
- [Setup email sending (optional)](./email.md)
|
||||
- [Setup email sending (optional)](../usage/configuration.md#email)
|
||||
- [Configure a reverse proxy (optional)](./reverse-proxy.md)
|
||||
- [Run the service](./running.md)
|
||||
@ -1,3 +0,0 @@
|
||||
# Email configuration
|
||||
|
||||
TODO: explain how to configure the email backend in the `email` section of the configuration file.
|
||||
@ -1,3 +1,115 @@
|
||||
# Configuring a reverse proxy
|
||||
|
||||
TODO: explain how to run a reverse proxy in front of the service, and which C-S API endpoints need to be proxied to the service.
|
||||
Although the service can be exposed directly to the internet, including handling the TLS termination, many deployments will want to run a reverse proxy in front of the service.
|
||||
|
||||
In those configuration, the service should be configured to listen on `localhost` or Unix domain socket.
|
||||
|
||||
## Example configuration
|
||||
|
||||
```yaml
|
||||
http:
|
||||
public_base: https://auth.example.com/
|
||||
listeners:
|
||||
- name: web
|
||||
resources:
|
||||
- name: discovery
|
||||
- name: human
|
||||
- name: oauth
|
||||
- name: compat
|
||||
- name: graphql
|
||||
# Uncomment to serve the assets by the service
|
||||
#- name: assets
|
||||
# path: ./share/assets/
|
||||
|
||||
binds:
|
||||
# Bind on a local port
|
||||
- host: localhost
|
||||
port: 8080
|
||||
|
||||
# OR bind on a Unix domain socket
|
||||
#- path: /var/run/mas.sock
|
||||
|
||||
# Optional: use the PROXY protocol
|
||||
#proxy_protocol: true
|
||||
```
|
||||
|
||||
## Example nginx configuration
|
||||
|
||||
Note that the assets can be served directly by nginx, and the `assets` resource can be removed from the service configuration.
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name auth.example.com;
|
||||
|
||||
ssl_certificate path/to/fullchain.pem;
|
||||
ssl_certificate_key path/to/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8080;
|
||||
# OR via the Unix domain socket
|
||||
#proxy_pass http://unix:/var/run/mas.sock;
|
||||
|
||||
proxy_http_version 1.1;
|
||||
|
||||
# Optional: use the PROXY protocol
|
||||
#proxy_protocol on;
|
||||
}
|
||||
|
||||
# Optional: serve the assets directly
|
||||
location /assets/ {
|
||||
root /path/to/share/assets/;
|
||||
|
||||
# Serve pre-compressed assets
|
||||
gzip_static on;
|
||||
# With the ngx_brotli module installed
|
||||
# https://github.com/google/ngx_brotli
|
||||
#brotli_static on;
|
||||
|
||||
# Cache assets for a year
|
||||
expires 365d;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For the compatibility layer, the following endpoints need to be proxied to the service:
|
||||
|
||||
- `/_matrix/client/*/login`
|
||||
- `/_matrix/client/*/logout`
|
||||
- `/_matrix/client/*/refresh`
|
||||
|
||||
For example, a nginx configuration could look like:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
|
||||
server_name matrix.example.com;
|
||||
|
||||
# Forward to the auth service
|
||||
location ~ ^/_matrix/client/(.*)/(login|logout|refresh) {
|
||||
proxy_pass http://localhost:8080;
|
||||
# OR via the Unix domain socket
|
||||
#proxy_pass http://unix:/var/run/mas.sock;
|
||||
|
||||
proxy_http_version 1.1;
|
||||
|
||||
# Optional: use the PROXY protocol
|
||||
#proxy_protocol on;
|
||||
}
|
||||
|
||||
# Forward to Synapse
|
||||
# as per https://matrix-org.github.io/synapse/latest/reverse_proxy.html#nginx
|
||||
location ~ ^(/_matrix|/_synapse/client) {
|
||||
proxy_pass http://localhost:8008;
|
||||
proxy_set_header X-Forwarded-For $remote_addr;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header Host $host;
|
||||
|
||||
client_max_body_size 50M;
|
||||
proxy_http_version 1.1;
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -21,4 +21,31 @@ Other than the binary, the service needs a few files to run:
|
||||
|
||||
Be sure to check the [installation instructions](./installation.md) for more information on how to get these files, and make sure the configuration file is updated accordingly.
|
||||
|
||||
TODO: systemd service, docker, etc.
|
||||
## Configure the HTTP server
|
||||
|
||||
The service can be configured to have multiple HTTP listeners, serving different resources.
|
||||
See the [`http.listeners`](../usage/configuration.md#http) 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`](../usage/configuration.md#http) 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`](../usage/configuration.md#telemetry): to setup metrics, tracing and Sentry crash reporting
|
||||
- [`email`](../usage/configuration.md#email): to setup email sending
|
||||
- [`password`](../usage/configuration.md#password): to enable/disable password authentication
|
||||
- [`upstream_oauth`](../usage/configuration.md#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`](../usage/cli/server.md) command:
|
||||
|
||||
```sh
|
||||
mas-cli server
|
||||
```
|
||||
|
||||
It is advised to run the service as a non-root user, using a tool like [`systemd`](https://www.freedesktop.org/wiki/Software/systemd/) to manage the service lifecycle.
|
||||
Reference in New Issue
Block a user