matrix/authentication-service
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-authentication-service.git synced 2025-07-31 09:24:31 +03:00
Code Activity

docs: Rename the "usage" section to "reference"

Browse Source
This commit is contained in:
Quentin Gliech
2024-04-18 11:59:16 +02:00
parent 201fb7359d
commit 87dc0debbf
17 changed files with 48 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/setup/database.md
View File

@ -2,7 +2,7 @@
The service uses a [PostgreSQL](https://www.postgresql.org/) database to store all of its state.
Although it may be possible to run with earlier versions, it is recommended to use **PostgreSQL 13** or later.
Connection to the database is configured in the [`database`](../usage/configuration.md#database) section of the configuration file.
Connection to the database is configured in the [`database`](../reference/configuration.md#database) section of the configuration file.
## Set up a database
@ -31,7 +31,7 @@ The above will create a user called `mas_user` with a password of your choice, a
## Service configuration
Once the database is created, the service needs to be configured to connect to it.
Edit the [`database`](../usage/configuration.md#database) section of the configuration file to match the database just created:
Edit the [`database`](../reference/configuration.md#database) section of the configuration file to match the database just created:
```yaml
database:
@ -52,7 +52,7 @@ database:
The service manages the database schema with embedded migrations.
Those migrations are run automatically when the service starts, but it is also possible to run them manually.
This is done using the [`database migrate`](../usage/cli/database.md#database-migrate) command:
This is done using the [`database migrate`](../reference/cli/database.md#database-migrate) command:
```sh
mas-cli database migrate
@ -63,6 +63,6 @@ mas-cli database 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)](../usage/configuration.md#email)
- [Setup email sending (optional)](../reference/configuration.md#email)
- [Configure a reverse proxy (optional)](./reverse-proxy.md)
- [Run the service](./running.md)

16
docs/setup/general.md
View File

@ -5,11 +5,11 @@
The service needs a few unique secrets and keys to work.
It mainly includes:
- the various signing keys referenced in the [`secrets.keys`](../usage/configuration.md#secrets) section
- the encryption key used to encrypt fields in the database and cookies, set in the [`secrets.encryption`](../usage/configuration.md#secrets) section
- a shared secret between the service and the homeserver, set in the [`matrix.secret`](../usage/configuration.md#matrix) section
- the various signing keys referenced in the [`secrets.keys`](../reference/configuration.md#secrets) section
- the encryption key used to encrypt fields in the database and cookies, set in the [`secrets.encryption`](../reference/configuration.md#secrets) section
- a shared secret between the service and the homeserver, set in the [`matrix.secret`](../reference/configuration.md#matrix) section
Although it is possible to generate these secrets manually, it is strongly recommended to use the [`config generate`](../usage/cli/config.md#config-generate) command to generate a configuration file with unique secrets and keys.
Although it is possible to generate these secrets manually, it is strongly recommended to use the [`config generate`](../reference/cli/config.md#config-generate) command to generate a configuration file with unique secrets and keys.
```sh
mas-cli config generate > config.yaml
@ -34,7 +34,7 @@ When using the `mas-cli`, multiple configuration files can be loaded, with the f
2. If not, load the files specified in the `MAS_CONFIG` environment variable if set, separated by `:`, relative to the current working directory
3. If not, load the file at `config.yaml` in the current working directory
The validity of the configuration file can be checked using the [`config check`](../usage/cli/config.md#config-check) command:
The validity of the configuration file can be checked using the [`config check`](../reference/cli/config.md#config-check) command:
```sh
# This will read both the `first.yaml` and `second.yaml` files
@ -47,7 +47,7 @@ MAS_CONFIG=first.yaml:second.yaml mas-cli config check
mas-cli config check
```
To help understand what the resulting configuration looks like after merging all the configuration files, the [`config dump`](../usage/cli/config.md#config-dump) command can be used:
To help understand what the resulting configuration looks like after merging all the configuration files, the [`config dump`](../reference/cli/config.md#config-dump) command can be used:
```sh
mas-cli config dump
@ -61,8 +61,8 @@ Many [tools in text editors](https://json-schema.org/implementations.html#editor
## Syncing the configuration file with the database
Some sections of the configuration file need to be synced every time the configuration file is updated.
This includes the [`clients`](../usage/configuration.md#clients) and [`upstream_oauth`](../usage/configuration.md#upstream-oauth) sections.
The configuration is synced by default on startup, and can be manually synced using the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command.
This includes the [`clients`](../reference/configuration.md#clients) and [`upstream_oauth`](../reference/configuration.md#upstream-oauth) sections.
The configuration is synced by default on startup, and can be manually synced using the [`config sync`](../reference/cli/config.md#config-sync---prune---dry-run) command.
By default, this will only add new clients and upstream OAuth providers and update existing ones, but will not remove entries that were removed from the configuration file.
To do so, use the `--prune` option:

8
docs/setup/homeserver.md
View File

@ -6,7 +6,7 @@ The authentication service needs to be able to call the Synapse admin API to pro
## Provision a client for the Homeserver to use
In the [`clients`](../usage/configuration.md#clients) section of the configuration file, add a new client with the following properties:
In the [`clients`](../reference/configuration.md#clients) section of the configuration file, add a new client with the following properties:
- `client_id`: a unique identifier for the client. It must be a valid [ULID](https://github.com/ulid/spec), and it happens that `0000000000000000000SYNAPSE` is a valid ULID.
- `client_auth_method`: set to `client_secret_basic`. Other methods are possible, but this is the easiest to set up.
@ -19,11 +19,11 @@ clients:
client_secret: "SomeRandomSecret"
```
**Don't forget to sync the configuration file** with the database after adding the client, using the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command.
**Don't forget to sync the configuration file** with the database after adding the client, using the [`config sync`](../reference/cli/config.md#config-sync---prune---dry-run) command.
## Configure the connection to the homeserver
In the [`matrix`](../usage/configuration.md#matrix) section of the configuration file, add the following properties:
In the [`matrix`](../reference/configuration.md#matrix) section of the configuration file, add the following properties:
- `homeserver`: corresponds to the `server_name` in the Synapse configuration file
- `secret`: a shared secret the service will use to call the homeserver admin API
@ -73,4 +73,4 @@ The following Matrix Client-Server API endpoints need to be handled by the authe
- [`/_matrix/client/*/logout`](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3logout)
- [`/_matrix/client/*/refresh`](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3refresh)
See the [reverse proxy configuration](./reverse-proxy.md) guide for more information.
See the [reverse proxy configuration](./reverse-proxy.md) guide for more information.

28
docs/setup/running.md
View File

@ -5,8 +5,8 @@ To fully function, the service needs to run two main components:
- An HTTP server
- A background worker
By default, the [`mas-cli server`](../usage/cli/server.md) 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`](../usage/cli/worker.md) command.
By default, the [`mas-cli server`](../reference/cli/server.md) 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`](../reference/cli/worker.md) command.
Both components are stateless, and can be scaled horizontally by running multiple instances of each.
@ -14,35 +14,35 @@ Both components are stateless, and can be scaled horizontally by running multipl
Other than the binary, the service needs a few files to run:
- The templates, referenced by the [`templates.path`](../usage/configuration.md#templates) configuration option
- The compiled policy, referenced by the [`policy.path`](../usage/configuration.md#policy) configuration option
- The frontend assets, referenced by the `path` option of the `assets` resource in the [`http.listeners`](../usage/configuration.md#http) configuration section
- The frontend manifest file, referenced by tge [`templates.assets_manifest`](../usage/configuration.md#templates) configuration option
- The templates, referenced by the [`templates.path`](../reference/configuration.md#templates) configuration option
- The compiled policy, referenced by the [`policy.path`](../reference/configuration.md#policy) configuration option
- The frontend assets, referenced by the `path` option of the `assets` resource in the [`http.listeners`](../reference/configuration.md#http) configuration section
- The frontend manifest file, referenced by tge [`templates.assets_manifest`](../reference/configuration.md#templates) configuration option
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.
## 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.
See the [`http.listeners`](../reference/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.
This is done using the [`http.public_base`](../reference/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
- [`telemetry`](../reference/configuration.md#telemetry): to setup metrics, tracing and Sentry crash reporting
- [`email`](../reference/configuration.md#email): to setup email sending
- [`password`](../reference/configuration.md#password): to enable/disable password authentication
- [`upstream_oauth`](../reference/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:
Once the configuration is done, the service can be started with the [`mas-cli server`](../reference/cli/server.md) command:
```sh
mas-cli server
@ -53,5 +53,5 @@ It is advised to run the service as a non-root user, using a tool like [`systemd
## Troubleshoot common issues
Once the service is running, it is possible to check its configuration using the [`mas-cli doctor`](../usage/cli/doctor.md) command.
Once the service is running, it is possible to check its configuration using the [`mas-cli doctor`](../reference/cli/doctor.md) command.
This should help diagnose common issues with the service configuration and deployment.

6
docs/setup/sso.md
View File

@ -12,9 +12,9 @@ A deployment which requires SAML or LDAP-based authentication should use a servi
Configuration of upstream providers is done in the `upstream_oauth2` section of the configuration file, which has a `providers` list.
Additions and changes to this sections are synced with the database on startup.
Removals need to be applied using the [`mas-cli config sync --prune`](../usage/cli/config.md#config-sync---prune---dry-run) command.
Removals need to be applied using the [`mas-cli config sync --prune`](../reference/cli/config.md#config-sync---prune---dry-run) command.
**An exhaustive list of all the parameters is available in the [configuration file reference](../usage/configuration.md#upstream_oauth2).**
**An exhaustive list of all the parameters is available in the [configuration file reference](../reference/configuration.md#upstream_oauth2).**
The general configuration usually goes as follows:
@ -62,7 +62,7 @@ Multiple authentication methods can be configured at the same time, in which cas
This is true if both the local password database and an upstream provider are configured, or if multiple upstream providers are configured.
In such cases, the `human_name` parameter of the provider configuration is used to display a human-readable name for the provider, and the `brand_name` parameter is used to show a logo for well-known providers.
If there is only one upstream provider configured and the local password database is disabled ([`passwords.enabled`](../usage/configuration.md#passwords) is set to `false`), the authentication service will automatically trigger an authorization flow with this provider.
If there is only one upstream provider configured and the local password database is disabled ([`passwords.enabled`](../reference/configuration.md#passwords) is set to `false`), the authentication service will automatically trigger an authorization flow with this provider.
## Sample configurations