letro/letro-authentication-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: greatly improve the setup documentation (WIP)

Browse Source
This commit is contained in:
Quentin Gliech
2023-07-25 19:33:44 +02:00
parent 6f65d8eca4
commit b0e16cc374
14 changed files with 405 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/README.md
View File

@@ -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 <https://matrix-org.github.io/matrix-authentication-service/>.
## Links

16
docs/SUMMARY.md
View File

@@ -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]()

4
docs/setup/README.md Normal file
View File

@@ -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).

74
docs/setup/database.md Normal file
View File

@@ -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://<user>:<password>@<host>/<database>
# -- OR --
# Separate parameters
host: <host>
port: 5432
username: <user>
password: <password>
database: <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)

3
docs/setup/email.md Normal file
View File

@@ -0,0 +1,3 @@
# Email configuration
TODO: explain how to configure the email backend in the `email` section of the configuration file.

80
docs/setup/general.md Normal file
View File

@@ -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).

76
docs/setup/homeserver.md Normal file
View File

@@ -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.

86
docs/setup/installation.md Normal file
View File

@@ -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-<commit 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.

3
docs/setup/reverse-proxy.md Normal file
View File

@@ -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.

24
docs/setup/running.md Normal file
View File

@@ -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.

18
docs/usage/cli/config.md
View File

@@ -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
```

120
docs/usage/configuration.md
View File

@@ -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

108
docs/usage/installation.md
View File

@@ -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 <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
```

13
docs/usage/usage.md
View File

@@ -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