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

Small documentation fixes

Browse Source 
- Removes mentions of the `mas-cli templates save` command
 - Removes the old `experimental` flags
 - Removes the old `policy.data.passwords` configs
 - Document the `policy.data.client_registration` flags
 - Remove references to the pre-built macOS binaries
 - Explains how to get syn2mas
 - State that you need to prepare the database before importing data
 - Clean up the reverse proxy documentation
 - Clarify that you don't need to provede templates/policy/assets
   manually when running the docker image
This commit is contained in:
Quentin Gliech
2024-08-16 12:36:00 +02:00
parent c8afc48e46
commit 62e01883b6
7 changed files with 152 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/reference/cli/templates.md
View File

@ -1,37 +1,15 @@
# `templates`
Helps customizing templates.
## `templates check`
## `templates save <path>`
Save the builtin template in the specified folder.
```console
$ mas-cli templates save ./templates
INFO mas_core::templates: Wrote template path="./templates/login.html"
INFO mas_core::templates: Wrote template path="./templates/register.html"
INFO mas_core::templates: Wrote template path="./templates/index.html"
INFO mas_core::templates: Wrote template path="./templates/reauth.html"
INFO mas_core::templates: Wrote template path="./templates/form_post.html"
INFO mas_core::templates: Wrote template path="./templates/error.html"
INFO mas_core::templates: Wrote template path="./templates/base.html"
```
By default this command won't overwrite existing files, but this behavior can be changed by adding the `--overwrite` flag.
## `templates check <path>`
Check the validity of the templates in the specified folder.
Check the validity of the templates loaded by the config.
It compiles the templates and then renders them with different contexts.
```console
$ mas-cli templates check ./templates
INFO mas_core::templates: Loading builtin templates
$ mas-cli templates check
INFO mas_core::templates: Loading templates from filesystem path=./templates/**/*.{html,txt}
INFO mas_core::templates::check: Rendering template name="login.html" context={"csrf_token":"fake_csrf_token","form":{"fields_errors":{},"form_errors":[],"has_errors":false}}
INFO mas_core::templates::check: Rendering template name="register.html" context={"__UNUSED":null,"csrf_token":"fake_csrf_token"}
INFO mas_core::templates::check: Rendering template name="index.html" context={"csrf_token":"fake_csrf_token","current_session":{"active":true,"created_at":"2021-09-24T13:26:52.962135085Z","id":1,"last_authd_at":"2021-09-24T13:26:52.962135316Z","user_id":2,"username":"john"},"discovery_url":"https://example.com/.well-known/openid-configuration"}
...
```
Builtin templates are still loaded by default when running this command, but this can be skipped by adding the `--skip-builtin` flag.

36
docs/reference/configuration.md
View File

@ -253,6 +253,11 @@ passwords:
# If disabled, users will only be able to log in using upstream OIDC providers
enabled: true
# Minimum complexity required for passwords, estimated by the zxcvbn algorithm
# Must be between 0 and 4, default is 3
# See https://github.com/dropbox/zxcvbn#usage for more information
minimum_complexity: 3
# List of password hashing schemes being used
# /!\ Only change this if you know what you're doing
# TODO: document this section better
@ -345,20 +350,13 @@ policy:
# Dynamic Client Registration
client_registration:
# don't require URIs to be on the same host. default: false
allow_host_mismatch: true
allow_host_mismatch: false
# allow non-SSL and localhost URIs. default: false
allow_insecure_uris: true
# Registration using passwords
passwords:
# minimum length of a password. default: 0
min_length: 8
# require at least one lowercase character in a password. default: false
require_lowercase: true
# require at least one uppercase character in a password. default: false
require_uppercase: true
# require at least one number in a password. default: false
require_number: true
allow_insecure_uris: false
# don't require clients to provide a client_uri. default: false
allow_missing_client_uri: false
# don't require clients to provide a contacts field. default: false
allow_missing_contacts: false
```
## `rate_limiting`
@ -638,16 +636,4 @@ experimental:
# Time-to-live of compatibility access tokens in seconds, when refresh tokens are supported. Defaults to 300, 5 minutes.
#compat_token_ttl: 300
# Whether to enable self-service password registration. Defaults to `true` if password authentication is enabled.
#password_registration_enabled: false
# Whether users are allowed to change their email addresses. Defaults to `true`.
#email_change_allowed: false
# Whether users are allowed to change their display names. Defaults to `true`.
#displayname_change_allowed: false
# Whether users are allowed to change their passwords. Defaults to `true`.
#password_change_allowed: false
```

2
docs/setup/general.md
View File

@ -18,7 +18,7 @@ mas-cli config generate > config.yaml
If you're using the docker container, the command `mas-cli` can be invoked with `docker run`:
```sh
docker run ghcr.io/matrix-org/matrix-authentication-service:main config generate > config.yaml
docker run ghcr.io/matrix-org/matrix-authentication-service config generate > config.yaml
```
This applies to all of the `mas-cli` commands in this document.

11
docs/setup/installation.md
View File

@ -2,12 +2,10 @@
## Pre-built binaries
Pre-built binaries can be found attached on each release, for Linux and macOS, on both `x86_64` and `aarch64` architectures.
Pre-built binaries can be found attached on each release, for Linux on both `x86_64` and `aarch64` architectures.
- [`mas-cli-aarch64-linux.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-aarch64-linux.tar.gz)
- [`mas-cli-x86_64-linux.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-x86_64-linux.tar.gz)
- [`mas-cli-aarch64-macos.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-aarch64-macos.tar.gz)
- [`mas-cli-x86_64-macos.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-x86_64-macos.tar.gz)
Each archive contains:
@ -27,7 +25,7 @@ Example shell commands to download and extract the `mas-cli` binary:
```sh
ARCH=x86_64 # or aarch64
OS=linux # or macos
OS=linux
VERSION=latest # or a specific version, like "v0.1.0"
# URL to the right archive
@ -41,13 +39,12 @@ curl -sL "$URL" | tar xzC /path/to/mas
/path/to/mas/mas-cli --help
```
**Note for macOS users**: the binaries are not signed, so if the archive is downloaded from a browser, it may be necessary to run `xattr -d com.apple.quarantine mas-cli` to remove the quarantine attribute on the binary.
## 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)
A pre-built Docker image is available here: [`ghcr.io/matrix-org/matrix-authentication-service:latest`](https://ghcr.io/matrix-org/matrix-authentication-service:latest)
The `latest` tag is built using the latest release.
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:

17
docs/setup/migration.md
View File

@ -18,6 +18,14 @@ There will be tools to help with the migration process itself. But these aren't
The deployment is non-trivial so it is important to read through and understand the steps involved and make a plan before starting.
### Get `syn2mas`
The easiest way to get `syn2mas` is through [`npm`](https://www.npmjs.com/package/@matrix-org/syn2mas):
```sh
npm install -g @matrix-org/syn2mas
```
### Run the migration advisor
You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver.
@ -38,6 +46,15 @@ If you are using an upstream SSO provider then you will need to provision the up
Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool.
### Prepare the MAS database
Once the database is created, it still needs to have its schema created and synced with the configuration.
This can be done with the following command:
```sh
mas-cli config sync
```
### Do a dry-run of the import to test
```sh

133
docs/setup/reverse-proxy.md
View File

@ -17,9 +17,7 @@ http:
- name: oauth
- name: compat
- name: graphql
# Uncomment to serve the assets by the service
#- name: assets
# path: ./share/assets/
- name: assets
binds:
# Bind on a local port
@ -37,9 +35,9 @@ http:
#proxy_protocol: true
```
## Example nginx configuration
## Base nginx configuration
Note that the assets can be served directly by nginx, and the `assets` resource can be removed from the service configuration.
A basic configuration for `nginx`, which proxies traffic to the service would look like this:
```nginx
server {
@ -51,32 +49,21 @@ server {
ssl_certificate_key path/to/privkey.pem;
location / {
proxy_http_version 1.1;
proxy_pass http://localhost:8080;
# OR via the Unix domain socket
#proxy_pass http://unix:/var/run/mas.sock;
proxy_http_version 1.1;
# Optional: use the PROXY protocol
# Forward the client IP address
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# or, using the PROXY protocol
#proxy_protocol on;
}
# Optional: serve the assets directly
location /assets/ {
root /path/to/share/assets/;
# Serve pre-compressed assets
gzip_static on;
# With the ngx_brotli module installed
# https://github.com/google/ngx_brotli
#brotli_static on;
# Cache assets for a year
expires 365d;
}
}
```
## Compatibility layer
For the compatibility layer, the following endpoints need to be proxied to the service:
- `/_matrix/client/*/login`
@ -94,13 +81,14 @@ server {
# Forward to the auth service
location ~ ^/_matrix/client/(.*)/(login|logout|refresh) {
proxy_http_version 1.1;
proxy_pass http://localhost:8080;
# OR via the Unix domain socket
#proxy_pass http://unix:/var/run/mas.sock;
proxy_http_version 1.1;
# Optional: use the PROXY protocol
# Forward the client IP address
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# or, using the PROXY protocol
#proxy_protocol on;
}
@ -117,3 +105,98 @@ server {
}
}
```
## Preserve the client IP
For rate-limiting and logging purposes, MAS needs to know the client IP address, which can be lost when using a reverse proxy.
There are two ways to preserve the client IP address
### `X-Forwarded-For` header
MAS can infer the client IP address from the `X-Forwarded-For` header.
It will trust the value for this header only if the request comes from a trusted reverse proxy.
The range of IPs that can be trusted is configured using the `trusted_proxies` configuration option, which has the default private IP ranges.
```yaml
http:
trusted_proxies:
- 192.168.0.0/16
- 172.16.0.0/12
- 10.0.0.0/10
- 127.0.0.1/8
- fd00::/8
- ::1/128
```
With nginx, this can be achieved by setting the `proxy_set_header` directive to `X-Forwarded-For $proxy_add_x_forwarded_for`.
### Proxy protocol
MAS supports the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to preserve the client IP address.
To enable it, enable the `proxy_protocol` option on the listener:
```yaml
http:
listeners:
- name: web
resources:
- name: discovery
- name: human
- name: oauth
- name: compat
- name: graphql
- name: assets
binds:
- address: "[::]:8080"
proxy_protocol: true
```
With nginx, this can be achieved by setting the `proxy_protocol` directive to `on` in the `location` block.
## Serve assets directly
To avoid unnecessary round-trips, the assets can be served directly by nginx, and the `assets` resource can be removed from the service configuration.
```yaml
http:
listeners:
- name: web
resources:
- name: discovery
- name: human
- name: oauth
- name: compat
- name: graphql
# MAS doesn't need to serve the assets anymore
#- name: assets
binds:
- address: "[::]:8080"
proxy_protocol: true
```
Make sure the assets directory served by nginx is up to date.
```nginx
server {
# --- SNIP ---
location / {
# --- SNIP ---
}
# Make nginx serve the assets directly
location /assets/ {
root /path/to/share/assets/;
# Serve pre-compressed assets
gzip_static on;
# With the ngx_brotli module installed
# https://github.com/google/ngx_brotli
#brotli_static on;
# Cache assets for a year
expires 365d;
}
}
```

5
docs/setup/running.md
View File

@ -21,6 +21,11 @@ Other than the binary, the service needs a few files to run:
Be sure to check the [installation instructions](./installation.md) for more information on how to get these files, and make sure the configuration file is updated accordingly.
**If you are using [the docker image](./installation.md#using-the-docker-image)**, everything is already included in the image at the right place, so in most cases you don't need to do anything.
**If you are using [the pre-built binaries](./installation.md#pre-built-binaries)**, those files are shipped alongside them in the `share` directory.
The default configuration will look for them from the current working directory, meaning that you don't have to adjust the paths, as long as you are running the service from the parent directory of the `share` directory.
## Configure the HTTP server
The service can be configured to have multiple HTTP listeners, serving different resources.