diff --git a/docs/README.md b/docs/README.md index 49c89f89f..e4dee1585 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,9 @@ # About this documentation -This documentation is intended to give an overview of how the `matrix-authentication-service` works, both from a admin perspective as well as from a developper perspective. +This documentation is intended to give an overview of how the `matrix-authentication-service` works, both from an admin perspective and from a developer perspective. + +The documentation itself is built using [mdBook](https://rust-lang.github.io/mdBook/). +A hosted version is available at . ## Links diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index c6618974c..ddc32ac28 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -4,10 +4,20 @@ - [About this documentation](./README.md) +# Setup + +- [Introduction](./setup/README.md) +- [Installation](./setup/installation.md) +- [General configuration](./setup/general.md) +- [Database setup](./setup/database.md) +- [Homeserver configuration](./setup/homeserver.md) +- [Configuring a reverse proxy](./setup/reverse-proxy.md) +- [Email configuration](./setup/email.md) +- [Running the service](./setup/running.md) + # Usage -- [Installation](./usage/installation.md) -- [Configuration](./usage/configuration.md) +- [Configuration file reference](./usage/configuration.md) - [Using the service](./usage/usage.md) - [Command line tool](./usage/cli/README.md) - [`config`](./usage/cli/config.md) @@ -20,5 +30,3 @@ - [Architecture](./development/architecture.md) - [Database](./development/database.md) -- [Routing with `axum`]() -- [Templates]() diff --git a/docs/setup/README.md b/docs/setup/README.md new file mode 100644 index 000000000..5baaa97c0 --- /dev/null +++ b/docs/setup/README.md @@ -0,0 +1,4 @@ +# Setup introduction + +This part of the documentation goes through installing the service, the important parts of the configuration file, and how to run the service. +The first section focuses on [installing the service](./installation.md). diff --git a/docs/setup/database.md b/docs/setup/database.md new file mode 100644 index 000000000..f37103a27 --- /dev/null +++ b/docs/setup/database.md @@ -0,0 +1,74 @@ +# Database configuration + +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. + +## Set up a database + +You will need to create a dedicated PostgreSQL database for the service. +The database can run on the same server as the service, or on a dedicated host. +The recommended setup for this database is to create a dedicated role and database for the service. + +Assuming your PostgreSQL database user is called `postgres`, first authenticate as the database user with: + +```sh +su - postgres +# Or, if your system uses sudo to get administrative rights +sudo -u postgres bash +``` + +Then, create a postgres user and a database with: + +```sh +# this will prompt for a password for the new user +createuser --pwprompt mas_user +createdb --owner=mas_user mas +``` + +The above will create a user called `mas_user` with a password of your choice, and a database called `mas` owned by the `mas_user` user. + +## 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: + +```yaml +database: + # Full connection string as per + # https://www.postgresql.org/docs/13/libpq-connect.html#id-1.7.3.8.3.6 + uri: postgres://:@/ + + # -- OR -- + # Separate parameters + host: + port: 5432 + username: + password: + database: +``` + +## Database migrations + +The service manages the database schema with embedded migrations. +Those migrations need to be run before the service can be started, and every time the service is upgraded. +This is done using the [`database migrate`](../usage/cli/database.md#database-migrate) command: + +```sh +mas-cli database migrate +``` + +It is also possible to run any pending migrations on service start, by setting the `--migrate` option to the [`server`](../usage/cli/server.md#server) command: + +```sh +mas-cli server --migrate +``` + +## Next steps + +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) + - [Configure a reverse proxy (optional)](./reverse-proxy.md) + - [Run the service](./running.md) \ No newline at end of file diff --git a/docs/setup/email.md b/docs/setup/email.md new file mode 100644 index 000000000..7cc4a419e --- /dev/null +++ b/docs/setup/email.md @@ -0,0 +1,3 @@ +# Email configuration + +TODO: explain how to configure the email backend in the `email` section of the configuration file. \ No newline at end of file diff --git a/docs/setup/general.md b/docs/setup/general.md new file mode 100644 index 000000000..00292c49c --- /dev/null +++ b/docs/setup/general.md @@ -0,0 +1,80 @@ +# General configuration + +## Initial configuration generation + +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 + +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. + +```sh +mas-cli config generate > config.yaml +``` + +**Note:** The generated configuration file is very extensive, and contains the default values for all the configuration options. +This will be made easier to read in the future, but in the meantime, it is recommended to strip untouched options from the configuration file. + +## Using and inspecting the configuration file + +When using the `mas-cli`, multiple configuration files can be loaded, with the following rule: + +1. If the `--config` option is specified, possibly multiple times, load the file at the specified path, 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 + +The validity of the configuration file can be checked using the [`config check`](../usage/cli/config.md#config-check) command: + +```sh +# This will read both the `first.yaml` and `second.yaml` files +mas-cli config check --config=first.yaml --config=second.yaml + +# This will also read both the `first.yaml` and `second.yaml` files +MAS_CONFIG=first.yaml:second.yaml mas-cli config check + +# This will only read the `config.yaml` file +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: + +```sh +mas-cli config dump +``` + +## Configuration schema + +The configuration file is validated against a JSON schema, which can be found [here](../config.schema.json). +Many [tools in text editors](https://json-schema.org/implementations.html#editors) can use this schema to provide autocompletion and validation. + +## 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. +Once the database is initialized, the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command can be used to sync the configuration file with the database: + +```sh +mas-cli config sync +``` + +By default, this will only add new clients and upstream OAuth providers, and will not remove entries that were removed from the configuration file. +To do so, use the `--purge` option: + +```sh +mas-cli config sync --purge +``` + +Before synchronizing the configuration file, it is *recommended* to do it in with the `--dry-run` option to see what will be changed, without committing the changes to the database: + +```sh +mas-cli config sync --dry-run +# with the --purge option +mas-cli config sync --dry-run --purge +``` + +## Next step + +After generating the configuration file, the next step is to [set up a database](./database.md). \ No newline at end of file diff --git a/docs/setup/homeserver.md b/docs/setup/homeserver.md new file mode 100644 index 000000000..f2faef851 --- /dev/null +++ b/docs/setup/homeserver.md @@ -0,0 +1,76 @@ +# Homeserver configuration + +The `matrix-authentication-service` is designed to be run alongside a Matrix homeserver. +It currently only supports [Synapse](https://github.com/matrix-org/synapse) through the experimental OAuth delegation feature. +The authentication service needs to be able to call the Synapse admin API to provision users through a shared secret, and Synapse needs to be able to call the service to verify access tokens using the OAuth 2.0 token introspection endpoint. + +## 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: + + - `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_secret`: a shared secret used for the homeserver to authenticate + +```yaml +clients: + - client_id: 0000000000000000000SYNAPSE + client_auth_method: client_secret_basic + 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. + +## Configure the connection to the homeserver + +In the [`matrix`](../usage/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 + - `endpoint`: the URL to which the homeserver is accessible from the service + +```yaml +matrix: + homeserver: localhost:8008 + secret: "AnotherRandomSecret" + endpoint: "http://localhost:8008" +``` + +## Configure the homeserver to delegate authentication to the service + +Set up the delegated authentication feature in the Synapse configuration in the `experimental_features` section: + +```yaml +experimental_features: + msc3861: + enabled: true + + # Synapse will call `{issuer}/.well-known/openid-configuration` to get the OIDC configuration + issuer: http://localhost:8080/ + + # Matches the `client_id` in the auth service config + client_id: 0000000000000000000SYNAPSE + # Matches the `client_auth_method` in the auth service config + client_auth_method: client_secret_basic + # Matches the `client_secret` in the auth service config + client_secret: "SomeRandomSecret" + + # Matches the `matrix.secret` in the auth service config + admin_token: "AnotherRandomSecret" + + # URL to advertise to clients where users can self-manage their account + account_management_url: "http://localhost:8080/account" +``` + +## Set up the compatibility layer + +The service exposes a compatibility layer to allow legacy clients to authenticate using the service. +This works by exposing a few Matrix endpoints that should be proxied to the service. + +The following Matrix Client-Server API endpoints need to be handled by the authentication service: + + - [`/_matrix/client/*/login`](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login) + - [`/_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. \ No newline at end of file diff --git a/docs/setup/installation.md b/docs/setup/installation.md new file mode 100644 index 000000000..7285559f3 --- /dev/null +++ b/docs/setup/installation.md @@ -0,0 +1,86 @@ +# Installation + +## Pre-built binaries + +Nightly builds for Linux and macOS (`arm64` and `x86-64`) are available through GitHub Actions artifacts. +They can be found for each commit on the [Actions tab](https://github.com/matrix-org/matrix-authentication-service/actions/workflows/build.yaml?query=branch%3Amain+is%3Asuccess). +The archives contain: + + - the `mas-cli` binary + - assets needed for running the service, including: + - `share/assets/`: the built frontend assets + - `share/manifest.json`: the manifest for the frontend assets + - `share/policy.wasm`: the built OPA policies + - `share/templates/`: the default templates + +The location of all these assets can be overridden in the [configuration file](./configuration.md). + +## Using the Docker image + +A pre-built Docker image is available here: [`ghcr.io/matrix-org/matrix-authentication-service:main`](https://ghcr.io/matrix-org/matrix-authentication-service:main) + +The `main` tag is built from the `main` branch, and each commit on the `main` branch is also tagged with a stable `sha-` tag. + +The image can also be built from the source: + +1. Get the source + ```sh + git clone https://github.com/matrix-org/matrix-authentication-service.git + cd matrix-authentication-service + ``` +1. Build the image + ```sh + docker build -t mas . + ``` + +## Building from the source + +Building from the source requires: + + - The latest stable [Rust toolchain](https://www.rust-lang.org/learn/get-started) + - [Node.js (18 and later)](https://nodejs.org/en/) and [npm](https://www.npmjs.com/get-npm) + - the [Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#running-opa) binary (or alternatively, Docker) + +1. Get the source + ```sh + git clone https://github.com/matrix-org/matrix-authentication-service.git + cd matrix-authentication-service + ``` +1. Build the frontend + ```sh + cd frontend + npm ci + npm run build + cd .. + ``` + This will produce a `frontend/dist` directory containing the built frontend assets. + This folder, along with the `frontend/dist/manifest.json` file, can be relocated, as long as the configuration file is updated accordingly. +1. Build the Open Policy Agent policies + ```sh + cd policies + make + cd .. + ``` + OR, if you don't have `opa` installed and want to build through the OPA docker image + ```sh + cd policies + make DOCKER=1 + cd .. + ``` + This will produce a `policies/policy.wasm` file containing the built OPA policies. + This file can be relocated, as long as the configuration file is updated accordingly. +1. Compile the CLI + ```sh + cargo build --release + ``` +1. Grab the built binary + ```sh + cp ./target/release/mas-cli ~/.local/bin # Copy the binary somewhere in $PATH + mas-cli --help # Should display the help message + ``` + +## Next steps + +The service needs some configuration to work. +This includes random, private keys and secrets. +Follow the [configuration guide](./general.md) to configure the service. diff --git a/docs/setup/reverse-proxy.md b/docs/setup/reverse-proxy.md new file mode 100644 index 000000000..69d5b4def --- /dev/null +++ b/docs/setup/reverse-proxy.md @@ -0,0 +1,3 @@ +# 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. \ No newline at end of file diff --git a/docs/setup/running.md b/docs/setup/running.md new file mode 100644 index 000000000..5d3bcaf5d --- /dev/null +++ b/docs/setup/running.md @@ -0,0 +1,24 @@ +# Running the service + +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. + +Both components are stateless, and can be scaled horizontally by running multiple instances of each. + +## Runtime requirements + +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 + +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. \ No newline at end of file diff --git a/docs/usage/cli/config.md b/docs/usage/cli/config.md index 09b5283fd..4edbbceb7 100644 --- a/docs/usage/cli/config.md +++ b/docs/usage/cli/config.md @@ -1,6 +1,6 @@ # `config` -Helps dealing with the configuration +Helps to deal with the configuration ## `config check` @@ -33,3 +33,19 @@ INFO generate: mas_config::oauth2: Generating keys... INFO generate:rsa: mas_config::oauth2: Done generating RSA key INFO generate:ecdsa: mas_config::oauth2: Done generating ECDSA key ``` + +## `config sync [--prune] [--dry-run]` + +Synchronize the configuration with the database. +This will synchronize the `clients` and `upstream_oauth` sections of the configuration with the database. +By default, it does not delete clients and upstreams that are not in the configuration anymore. Use the `--prune` option to do so. +The `--dry-run` option will log the changes that would be made, without actually making them. + +```console +$ mas-cli config sync --prune --config=config.yaml +INFO cli.config.sync: Syncing providers and clients defined in config to database prune=true dry_run=false +INFO cli.config.sync: Updating provider provider.id=01H3FDH2XZJS8ADKRGWM84PZTY +INFO cli.config.sync: Adding provider provider.id=01H3FDH2XZJS8ADKRGWM84PZTF +INFO cli.config.sync: Deleting client client.id=01GFWRB9MYE0QYK60NZP2YF905 +INFO cli.config.sync: Updating client client.id=01GFWRB9MYE0QYK60NZP2YF904 +``` \ No newline at end of file diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index bf21a05f6..0c294b24c 100644 --- a/docs/usage/configuration.md +++ b/docs/usage/configuration.md @@ -1,102 +1,6 @@ -# Configuration +# Configuration file reference -The service needs some configuration to work. -This includes random, private keys and secrets. - -A sample configuration file can be generated using `mas-cli config generate`. - -```sh -mas-cli config generate > config.yaml -mas-cli config check --config=config.yaml -# if --config is omitted, it will try to load `config.yaml` -# in the current working directory -mas-cli config check -``` - -Or, with Docker: - -```sh -docker run --rm \ - ghcr.io/matrix-org/matrix-authentication-service:main \ - config generate > config.yaml - -docker run --rm -v `pwd`:/wd \ - ghcr.io/matrix-org/matrix-authentication-service:main \ - --config=/wd/config.yaml config dump - -# or, mounting only the config file and omitting `--config` -docker run --rm -v `pwd`/config.yaml:/config.yaml \ - ghcr.io/matrix-org/matrix-authentication-service:main \ - config dump -``` - -Note that with Docker, the config file must be mounted inside the container with `-v/--volume`. - -Update the database URI in `config.yaml` to your database, -e.g. `postgresql://postgres:postgres@localhost/postgres` - -See also the next section for a [minimal configuration](#minimal-configuration) - -## Minimal configuration - -Here is a minimal configuration needed to have the server running. -It is strongly recommended to generate the initial configuration using the `config generate` to have unique secrets and signing keys. -Check the next section to know about each section. - -```yaml -# config.yaml -database: - uri: postgresql:///matrix_auth - -http: - public_base: http://localhost:8080 - -secrets: - encryption: c7e42fb8baba8f228b2e169fdf4c8216dffd5d33ad18bafd8b928c09ca46c718 - - keys: - - type: rsa - key: | - -----BEGIN PRIVATE KEY----- - MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7iinu0NXjWP5/ - /4OqyqOMI5uLJIHSrYIZLUlWMldtXmNy0c/pan+gxvZogiYx0cNydO/FogNbC4oD - yj7RIF+QcWJ8wcdG94/P+Xs3HFQzIZfwF+78RWQQJ7nQFekXJ1wQSXV4giw9b4XR - YkoVhHlyxyYGBFffO//DtYVto4uHvXVL0M27bV6l1K8VKspF72gb8Vt44V8OX5hT - sEsYW8SjOD1neEoVKiY6XP63cAG9FTB4a4sKkcUqwjrKEYKio/JLujmCl96eLN18 - cuqr6XuSDKvuVJtb+ZNLJi61vIOlD8cz3wu37hr3PCUZ+Ko9Ley+QfopJ3WYFxrI - IjQKb0W5AgMBAAECggEBAK87ZfsTfwczPHn1Ed4gAbkL/GaC8hscrJdBzWiRGUfE - DkBW82IydJaR0ePM2EtsqKblxLRxsZj8qzTnYNKe4SxiBZh0p/MTlnjJr+vKuJIe - LY3VjySA4gKGXASmtGlCCa/eM7kqSJQPBIakxHxej+xDULAGluSrd0wy7D2JtvJY - 5By+2apILUujBZZU/iUyB2AqK6IrzALo2gTV9Jhun9Wz0k3DXZBGd41v42BhZ+Rx - bHHgpuUTyDQOpKqJ5g1kN4qGlN/CeoontxcE5NOSgtipWeQEuelT8t4eZKHTXBS+ - Byd+uFe8oobWRY2crLptX8TZEENH7wX7y2YgNYUbeZECgYEA95YRhDuukcrDiNuF - fOXs+99XFORsKTbtZYwrouc7PI2CYb0I9ezoQMu3dzWIwOTUQHea5qCo/dYzbeED - fNzwPb2zaWaWFbkEWVTOwRewL+NfP+Ek2Nml+dVJm3d35qdIHYV+9gAcI87iCHxA - gqc13ZS4ba+5/vV6OYwNSAeW0TcCgYEAwem1F9zhVVOIReh3JaJLpZn0xuvZs5kN - TzvFXar33LKdulk5liC3L7ZrqspGESU0JC3pANR8PwuNteEEdHnkC5UTEqMf/fxG - j5CObJl+e2CiV2CNbe+3IQ1PKSxopD+Sq65ze7aP2moVZg94mbw4dsN+uY5QEql1 - Bmq0b7Wm2I8CgYBOqlDgefIKgqlEF7O/LnLwyFKr4bP4GGqvZC0NMnkg0TmHAoAR - W3ej9tZROyI7X7mMzjPaaVuoY2Gt3Nu11aFDjL2vlJfFSSb3lzmmInepj43ZBxkl - CWpyCfG8QuZG1AnWz266jOhj/DzXQ1tf5+72e2Vp/HaVaruuAzDJHRgvWwKBgAHy - aMEOlKyYpBufk+Kq2HuXKh/9KjhlZv7OqNKh7s8mc/L1BmD9fxlZiYczdLSjXPyo - AVjiyUSQxyF2WucYejOrkX90Z9PS/ppeZy+r8tsmQzsBWyopZ/tK+Op+6aYMhVp3 - 6+zoDlWxDvnxWdKhUyfOGq2eQiuNzAD+fUVJ25z9AoGARUJ4C87X7vH4QnsIE0g+ - ni0xSs8DgSq0v8+cJ7xwyN+NnC6eeU9N2U/m/5anLEM2GFjo4kghLDkC/2urc8dD - UtiisQjWz3O88QHqOvclEAmveuxfCYr/A/CWGdkH3YoK+AXIj3fkwb2Qd//rJ9zL - dT3XPCRatoVKLNKzUGNVcFM= - -----END PRIVATE KEY----- - - type: ecdsa - key: | - -----BEGIN PRIVATE KEY----- - MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgaa7KvLdq72Nb7i7pGm/6 - SCW0RAKFcVwz7P9/8Wo2TTShRANCAATlTf0uyezm7riXjZdn1XND00uf4d1tc1jc - V4CiFiDQsDX+3znAGxqhTuoOkVn/G5lwgE1cgTX57r9cyYkso9UY - -----END PRIVATE KEY----- -``` - -## Configuration sections - -### `http` +## `http` Controls the web server. @@ -130,7 +34,7 @@ http: issuer: http://[::]:8080/ ``` -### `database` +## `database` Configure how to connect to the PostgreSQL database. @@ -157,7 +61,7 @@ database: max_lifetime: 1800 ``` -### `templates` +## `templates` Allows loading custom templates @@ -167,11 +71,11 @@ templates: # This is relative to the current working directory, *not* the config file path: /to/templates - # Whether builtin should be loaded or not - builtin: true + # Path to the frontend assets manifest file + assets_manifest: /to/manifest.json ``` -### `clients` +## `clients` List of OAuth 2.0/OIDC clients and their keys/secrets. Each `client_id` must be a [ULID](https://github.com/ulid/spec). @@ -189,19 +93,19 @@ clients: client_auth_method: none ``` -### `secrets` +## `secrets` Signing and encryption secrets ```yaml secrets: - # Encrytion secret (used for encrypting cookies) + # Encryption secret (used for encrypting cookies and database fields) encryption: c7e42fb8baba8f228b2e169fdf4c8216dffd5d33ad18bafd8b928c09ca46c718 # Signing keys keys: # It needs at least an RSA key to work properly - - type: "rsa" + - kid: "ahM2bien" key: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7iinu0NXjWP5/ @@ -231,7 +135,7 @@ secrets: UtiisQjWz3O88QHqOvclEAmveuxfCYr/A/CWGdkH3YoK+AXIj3fkwb2Qd//rJ9zL dT3XPCRatoVKLNKzUGNVcFM= -----END PRIVATE KEY----- - - type: "ecdsa" + - kid: "iv1aShae" key: | -----BEGIN PRIVATE KEY----- MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgaa7KvLdq72Nb7i7pGm/6 @@ -240,7 +144,7 @@ secrets: -----END PRIVATE KEY----- ``` -### `policy` +## `policy` Policy settings diff --git a/docs/usage/installation.md b/docs/usage/installation.md deleted file mode 100644 index b4390a37b..000000000 --- a/docs/usage/installation.md +++ /dev/null @@ -1,108 +0,0 @@ -# Installation - -## Requirements - - - A PostgreSQL 13+ database - - Either: - - A [Rust toolchain with Cargo](https://www.rust-lang.org/learn/get-started) (recommended for development), - - [Node.js 18 or later with npm](https://nodejs.org/) and - - [Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#1-download-opa) - - **or** [Docker](https://www.docker.com/get-started) (or a compatible container runtime) - -## Installing from the source - -1. Get the source - ```sh - git clone https://github.com/matrix-org/matrix-authentication-service.git - cd matrix-authentication-service - ``` -1. Build the frontend - ```sh - cd frontend - npm ci - npm run build - cd .. - ``` -1. Build the Open Policy Agent policies - ```sh - cd policies - make - cd .. - ``` - OR, if you don't have `opa` installed and want to build through the OPA docker image - ```sh - cd policies - make DOCKER=1 - cd .. - ``` -1. Compile the CLI - ```sh - cargo build --release - ``` -1. Grab the built binary - ```sh - cp ./target/release/mas-cli ~/.local/bin # Copy the binary somewhere in $PATH - mas-cli --help # Should display the help message - ``` - -## Running from the Docker image - -A Docker image is available here: [`ghcr.io/matrix-org/matrix-authentication-service:main`](https://ghcr.io/matrix-org/matrix-authentication-service:main) - ---- - -```sh -docker run --rm ghcr.io/matrix-org/matrix-authentication-service:main --help -``` -``` -mas-cli - -USAGE: - mas-cli [OPTIONS] [SUBCOMMAND] - -FLAGS: - -h, --help Print help information - -V, --version Print version information - -OPTIONS: - -c, --config ... Path to the configuration file [default: config.yaml] - -SUBCOMMANDS: - config Configuration-related commands - database Manage the database - help Print this message or the help of the given subcommand(s) - manage Manage the instance - server Runs the web server - templates Templates-related commands -``` - -Note that when running in a Docker environment - ---- - -The next step is to generate the configuration file and tweak it to reach the PostgreSQL database. - -## Database - -You can run a PostgreSQL database locally via docker. -```sh -docker run -p 5432:5432 -e 'POSTGRES_USER=postgres' -e 'POSTGRES_PASSWORD=postgres' -e 'POSTGRES_DATABASE=postgres' postgres -``` - -Or if you uses your own shared database server you can previously create the database. - -Assuming your PostgreSQL database user is called `postgres`, first authenticate as the database user with: - -```sh -su - postgres -# Or, if your system uses sudo to get administrative rights -sudo -u postgres bash -``` - -Then, create a postgres user and a database with: -``` -# this will prompt for a password for the new user -createuser --pwprompt matrix_authentication_user - -createdb --owner=matrix_authentication_user matrix_authentication -``` diff --git a/docs/usage/usage.md b/docs/usage/usage.md index ffb29bf75..293b2a534 100644 --- a/docs/usage/usage.md +++ b/docs/usage/usage.md @@ -35,7 +35,7 @@ docker run --rm \ ## 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). +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 @@ -48,12 +48,19 @@ Add the following section to the server configuration file `config.yaml`: ```yaml clients: - - client_id: oidc-playground + # 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/) @@ -61,7 +68,7 @@ clients: - 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 `oidc-playground` and the Client Secret to `verysecret` (must match the ones in the configuration) + - 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