matrix/authentication-service
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-authentication-service.git synced 2025-08-06 06:02:40 +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

21
docs/SUMMARY.md
View File

@@ -17,17 +17,18 @@
- [Running the service](./setup/running.md) - [Running the service](./setup/running.md)
- [Migrating an existing homeserver](./setup/migration.md) - [Migrating an existing homeserver](./setup/migration.md)
# Usage # Reference
- [Configuration file reference](./usage/configuration.md) - [Configuration file reference](./reference/configuration.md)
- [Using the service](./usage/usage.md) - [GraphQL API](./reference/graphql.md)
- [Command line tool](./usage/cli/README.md) - [OAuth 2.0 scopes](./reference/scopes.md)
- [`config`](./usage/cli/config.md) - [Command line tool](./reference/cli/README.md)
- [`database`](./usage/cli/database.md) - [`config`](./reference/cli/config.md)
- [`manage`](./usage/cli/manage.md) - [`database`](./reference/cli/database.md)
- [`server`](./usage/cli/server.md) - [`manage`](./reference/cli/manage.md)
- [`templates`](./usage/cli/templates.md) - [`server`](./reference/cli/server.md)
- [`doctor`](./usage/cli/doctor.md) - [`templates`](./reference/cli/templates.md)
- [`doctor`](./reference/cli/doctor.md)
# Development # Development

0
docs/usage/cli/README.md → docs/reference/cli/README.md
View File

0
docs/usage/cli/config.md → docs/reference/cli/config.md
View File

0
docs/usage/cli/database.md → docs/reference/cli/database.md
View File

0
docs/usage/cli/doctor.md → docs/reference/cli/doctor.md
View File

0
docs/usage/cli/manage.md → docs/reference/cli/manage.md
View File

0
docs/usage/cli/server.md → docs/reference/cli/server.md
View File

0
docs/usage/cli/templates.md → docs/reference/cli/templates.md
View File

4
docs/usage/configuration.md → docs/reference/configuration.md
View File

@@ -157,7 +157,7 @@ clients:
client_auth_method: none client_auth_method: none
``` ```
**Note:** any additions or modification in this list are synced with the database on server startup. Removed entries are only removed with the [`config sync --prune`](../usage/cli/config.md#config-sync---prune---dry-run) command. **Note:** any additions or modification in this list are synced with the database on server startup. Removed entries are only removed with the [`config sync --prune`](../reference/cli/config.md#config-sync---prune---dry-run) command.
## `secrets` ## `secrets`
@@ -351,7 +351,7 @@ email:
Settings related to upstream OAuth 2.0/OIDC providers. Settings related to upstream OAuth 2.0/OIDC providers.
Additions and modifications within this section are synced with the database on server startup. Additions and modifications within this section are synced with the database on server startup.
Removed entries are only removed with the [`config sync --prune`](../usage/cli/config.md#config-sync---prune---dry-run) command. Removed entries are only removed with the [`config sync --prune`](./cli/config.md#config-sync---prune---dry-run) command.
#### `upstream_oauth2.providers` #### `upstream_oauth2.providers`

1
docs/reference/graphql.md Normal file
View File

@@ -0,0 +1 @@
# GraphQL API

1
docs/reference/scopes.md Normal file
View File

@@ -0,0 +1 @@
# OAuth 2.0 scopes

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. 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. 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 ## 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 ## Service configuration
Once the database is created, the service needs to be configured to connect to it. 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 ```yaml
database: database:
@@ -52,7 +52,7 @@ database:
The service manages the database schema with embedded migrations. 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. 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 ```sh
mas-cli database migrate mas-cli database migrate
@@ -63,6 +63,6 @@ mas-cli database migrate
Once the database is up, the remaining steps are to: Once the database is up, the remaining steps are to:
- [Set up the connection to the homeserver (recommended)](./homeserver.md) - [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) - [Configure a reverse proxy (optional)](./reverse-proxy.md)
- [Run the service](./running.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. The service needs a few unique secrets and keys to work.
It mainly includes: It mainly includes:
- the various signing keys referenced in the [`secrets.keys`](../usage/configuration.md#secrets) 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`](../usage/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`](../usage/configuration.md#matrix) 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 ```sh
mas-cli config generate > config.yaml 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 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 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 ```sh
# This will read both the `first.yaml` and `second.yaml` files # 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 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 ```sh
mas-cli config dump 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 ## Syncing the configuration file with the database
Some sections of the configuration file need to be synced every time the configuration file is updated. 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. 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`](../usage/cli/config.md#config-sync---prune---dry-run) command. 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. 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: To do so, use the `--prune` option:

6
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 ## 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_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. - `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" 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 ## 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 - `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 - `secret`: a shared secret the service will use to call the homeserver admin API

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 - An HTTP server
- A background worker - A background worker
By default, the [`mas-cli server`](../usage/cli/server.md) command will start both components. 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`](../usage/cli/worker.md) command. 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. 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: 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 templates, referenced by the [`templates.path`](../reference/configuration.md#templates) configuration option
- The compiled policy, referenced by the [`policy.path`](../usage/configuration.md#policy) 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`](../usage/configuration.md#http) configuration section - 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`](../usage/configuration.md#templates) configuration option - 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. 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 ## Configure the HTTP server
The service can be configured to have multiple HTTP listeners, serving different resources. 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. 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. 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 ## Tweak the remaining configuration
A few configuration sections might still require some tweaking, including: A few configuration sections might still require some tweaking, including:
- [`telemetry`](../usage/configuration.md#telemetry): to setup metrics, tracing and Sentry crash reporting - [`telemetry`](../reference/configuration.md#telemetry): to setup metrics, tracing and Sentry crash reporting
- [`email`](../usage/configuration.md#email): to setup email sending - [`email`](../reference/configuration.md#email): to setup email sending
- [`password`](../usage/configuration.md#password): to enable/disable password authentication - [`password`](../reference/configuration.md#password): to enable/disable password authentication
- [`upstream_oauth`](../usage/configuration.md#upstream-oauth): to configure upstream OAuth providers - [`upstream_oauth`](../reference/configuration.md#upstream-oauth): to configure upstream OAuth providers
## Run the service ## 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 ```sh
mas-cli server 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 ## 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. 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. 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. 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: 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. 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. 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 ## Sample configurations

81
docs/usage/usage.md
View File

@@ -1,81 +0,0 @@
# Using the service
## Running
Once the configuration is done, one should run the database migrations
(database schema upgrade, also for setup) by running
```sh
mas-cli database migrate
```
The server can then be started by running
```sh
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:
```sh
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`](http://localhost:8080/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`:
```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:
```sh
mas-cli config sync
```
### Step 2: Change the playground configuration
- Navigate to [the playground](https://openidconnect.net/)
- 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.