Merge pull request #3641 from luixxiul/fix

Update docs/configuring-playbook-conduit.md and docs/configuring-playbook-dendrite.md

CHANGELOG.md

@@ -1,3 +1,16 @@
+# 2024-10-19
+
+## Support for Matrix Authentication Service
+
+The playbook now supports installing and configuring [Matrix Authentication Service](./docs/configuring-playbook-matrix-authentication-service.md) (MAS).
+
+Huge thanks to [Quentin Gliech](https://github.com/sandhose) from the [Element](https://element.io/) / [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service) team for answering our numerous questions about MAS.
+
+This is an **experimental service** and there are **still certain issues with it** (see [Expectations](./docs/configuring-playbook-matrix-authentication-service.md#expectations)). Matrix server administrators should only consider switching if they identify with one or more [reasons to use Matrix Authentication Service](./docs/configuring-playbook-matrix-authentication-service.md#reasons-to-use-matrix-authentication-service). As MAS adoption improves and more services are adjusted to support it, we expect that using MAS will become the norm.
+
+Our [Setting up Matrix Authentication Service](./docs/configuring-playbook-matrix-authentication-service.md) documentation page has more details about this new service, what you might expect from the switch and how you can migrate your existing (Synapse) homeserver setup to MAS.
+
+
 # 2024-09-27
 
 ## (BC Break) Postgres & Traefik roles have been relocated and variable names need adjustments
@@ -2388,10 +2401,10 @@ The new version of [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bri
 
 1. Add the following to your `vars.yml` file: `matrix_sms_bridge_container_extra_arguments=['--env SPRING_PROFILES_ACTIVE=initialsync']`
 2. Login to your host shell and remove old systemd file from your host: `rm /etc/systemd/system/matrix-sms-bridge-database.service`
-2. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-sms-bridge,start`
-3. Login to your host shell and check the logs with `journalctl -u matrix-sms-bridge` until the sync finished.
-4. Remove the var from the first step.
-5. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`.
+3. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-sms-bridge,start`
+4. Login to your host shell and check the logs with `journalctl -u matrix-sms-bridge` until the sync finished.
+5. Remove the var from the first step.
+6. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`.
 
 # 2020-11-10
 

docs/configuring-playbook-cactus-comments.md

@@ -4,8 +4,7 @@ The playbook can install and configure the [Cactus Comments](https://cactus.chat
 
 Cactus Comments is a **federated comment system** built on Matrix. It respects your privacy, and puts you in control.
 
-See the project's [documentation](https://cactus.chat/docs/getting-started/introduction/) to learn what it
-does and why it might be useful to you.
+See the project's [documentation](https://cactus.chat/docs/getting-started/introduction/) to learn what it does and why it might be useful to you.
 
 The playbook contains 2 roles for configuring different pieces of the Cactus Comments system:
 
@@ -17,7 +16,7 @@ You can enable whichever component you need (typically both).
 
 ## Configuration
 
-Add the following block to your `vars.yaml` and make sure to exchange the tokens to randomly generated values.
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 #################
@@ -54,25 +53,41 @@ Upon starting Cactus Comments, a `bot.cactusbot` user account is created automat
 
 To get started, send a `help` message to the `@bot.cactusbot:example.com` bot to confirm it's working.
 
-Then, register a site by typing: `register <sitename>`. You will then be invited into a moderation room.
+Then, register a site by sending `register <YourSiteName>` (where `<YourSiteName>` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
 
-Now you are good to go and can include the comment section on your website!
+Now you are good to go and can embed the comment section on your website!
 
-**Careful**: To really make use of self-hosting you need change a few things in comparison to the official docs!
+## Embed Cactus Comments
 
-Insert the following snippet into you page and make sure to replace `example.com` with your base domain!
+The official [documentation](https://cactus.chat/docs/getting-started/quick-start/) provides a useful guide to embed Cactus Comments on your website.
+
+After including the JavaScript and CSS asset files, insert a `<div>` where you'd like to display the comment section:
+
+````html
+<div id="comment-section"></div>
+````
+
+Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `<YourSiteName>` with the one that has been registered above:
 
 ```html
-<script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
-<link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
-<div id="comment-section"></div>
 <script>
 initComments({
   node: document.getElementById("comment-section"),
   defaultHomeserverUrl: "https://matrix.example.com:8448",
   serverName: "example.com",
-  siteName: "YourSiteName",
+  siteName: "<YourSiteName>",
   commentSectionId: "1"
 })
 </script>
 ```
+
+### Adjust the domain name for self-hosting
+
+To have the assets served from your homeserver (not from `cactus.chat`), you need to adjust the domain name on the official documentation.
+
+Make sure to replace `example.com` with your base domain before you include the following lines, instead of the one provided by the official documentation:
+
+```html
+<script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
+<link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
+```

docs/configuring-playbook-client-cinny.md

@@ -1,14 +1,14 @@
 # Configuring Cinny (optional)
 
 This playbook can install the [cinny](https://github.com/ajbura/cinny) Matrix web client for you.
-Cinny is a web client focusing primarily on simple, elegant and secure interface.
-Cinny can be installed alongside or instead of Element.
+
+Cinny is a web client focusing primarily on simple, elegant and secure interface. It can be installed alongside or instead of Element.
 
 ## DNS
 
-You need to add a `cinny.example.com` DNS record so that Cinny can be accessed.
-By default Cinny will use https://cinny.example.com so you will need to create an CNAME record
-for `cinny`. See [Configuring DNS](configuring-dns.md).
+You need to add a DNS record so that Cinny can be accessed.
+
+By default Cinny will use https://cinny.example.com so you will need to create an CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md).
 
 If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
 

docs/configuring-playbook-client-hydrogen.md

@@ -1,14 +1,14 @@
 # Configuring Hydrogen (optional)
 
 This playbook can install the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
-Hydrogen is a lightweight web client that supports mobile and legacy web browsers.
-Hydrogen can be installed alongside or instead of Element.
+
+Hydrogen is a lightweight web client that supports mobile and legacy web browsers. It can be installed alongside or instead of Element.
 
 ## DNS
 
-You need to add a `hydrogen.example.com` DNS record so that Hydrogen can be accessed.
-By default Hydrogen will use https://hydrogen.example.com so you will need to create an CNAME record
-for `hydrogen`. See [Configuring DNS](configuring-dns.md).
+You need to add a DNS record so that Hydrogen can be accessed.
+
+By default Hydrogen will use https://hydrogen.example.com so you will need to create an CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md).
 
 If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
 

docs/configuring-playbook-client-schildichat.md

@@ -1,16 +1,16 @@
 # Configuring SchildiChat (optional)
 
 This playbook can install the [SchildiChat](https://github.com/SchildiChat/schildichat-desktop) Matrix web client for you.
-SchildiChat is a feature-rich messenger for Matrix based on Element with some extras and tweaks.
-SchildiChat can be installed alongside or instead of Element.
+
+SchildiChat is a feature-rich messenger for Matrix based on Element with some extras and tweaks. It can be installed alongside or instead of Element.
 
 **WARNING**: SchildiChat Web is based on Element-web, but its releases are lagging behind. As an example (from 2024-02-26), SchildiChat Web is 22 releases behind (it being based on element-web `v1.11.36`, while element-web is now on `v1.11.58`). Element-web frequently suffers from security issues, so running something based on an ancient Element-web release is **dangerous**. Use SchildiChat Web at your own risk!
 
 ## DNS
 
-You need to add a `schildichat.example.com` DNS record so that SchildiChat can be accessed.
-By default SchildiChat will use https://schildichat.example.com so you will need to create an CNAME record
-for `schildichat`. See [Configuring DNS](configuring-dns.md).
+You need to add a DNS record so that SchildiChat can be accessed.
+
+By default SchildiChat will use https://schildichat.example.com so you will need to create an CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md).
 
 If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
 

docs/configuring-playbook-conduit.md

@@ -8,16 +8,17 @@ By default, this playbook configures the [Synapse](https://github.com/element-hq
 
 - **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
 
+## Adjusting the playbook configuration
 
-## Installing
-
-To use Conduit, you **generally** need the following additional `vars.yml` configuration:
+To use Conduit, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_homeserver_implementation: conduit
 ```
 
-However, since Conduit is difficult (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) when it comes to creating the first user account and does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following flow:
+## Creating the first user account
+
+Since it is difficult to create the first user account on Conduit (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) and it does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following procedure:
 
 1. Add `matrix_conduit_allow_registration: true` to your `vars.yml` the first time around, temporarily
 2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` - see [Installing](installing.md))

docs/configuring-playbook-dendrite.md

@@ -8,7 +8,17 @@ By default, this playbook configures the [Synapse](https://github.com/element-hq
 
 - **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
 
-The playbook provided settings for Dendrite are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template.
+## Adjusting the playbook configuration
+
+To use Dendrite, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_homeserver_implementation: dendrite
+```
+
+The playbook provides lots of customization variables you could use to change Dendrite's settings.
+
+Their defaults are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template.
 
 **If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
 
@@ -24,8 +34,4 @@ Alternatively, **if there is no pre-defined variable** for a Dendrite setting yo
 
 ## Installing
 
-To use Dendrite, you **generally** need the following additional `vars.yml` configuration:
-
-```yaml
-matrix_homeserver_implementation: dendrite
-```
+After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`

docs/configuring-playbook-email.md

@@ -7,7 +7,9 @@ This may or may not work, depending on your domain configuration (SPF settings,
 
 By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.
 
-**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.
+⚠ **Warning**: On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server).
+
+💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.
 
 
 ## Firewall settings

docs/configuring-playbook-matrix-authentication-service.md

@@ -0,0 +1,394 @@
+# Matrix Authentication Service (MAS)
+
+This playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) - a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/).
+
+Matrix Authentication Service is an implementation of [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and still work in progress, tracked at the [areweoidcyet.com](https://areweoidcyet.com/) website.
+
+**Before going through with starting to use Matrix Authentication Service**, make sure to read:
+
+- the [Reasons to use Matrix Authentication Service](#reasons-to-use-matrix-authentication-service) section below
+- the [Expectations](#expectations) section below
+- the [FAQ section on areweoidcyet.com](https://areweoidcyet.com/#faqs)
+
+**If you've already been using Synapse** and have user accounts in its database, you can [migrate to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service).
+
+
+## Reasons to use Matrix Authentication Service
+
+You may be wondering whether you should make the switch to Matrix Authentication Service (MAS) or keep using your existing authentication flow via Synapse (password-based or [OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)-enabled).
+
+Matrix Authentication Service is **still an experimental service** and **not a default** for this Ansible playbook.
+
+The [Expectations](#expectations) section contains a list of what works and what doesn't (**some services don't work with MAS yet**), as well as the **relative irreversability** of the migration process.
+
+Below, we'll try to **highlight some potential reasons for switching** to Matrix Authentication Service:
+
+- To use SSO in [Element X](https://element.io/blog/element-x-ignition/). The old [Synapse OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) login flow is only supported in old Element clients and will not be supported in Element X. Element X will only support the new SSO-based login flow provided by MAS, so if you want to use SSO with Element X, you will need to switch to MAS.
+
+- To help drive adoption of the "Next-generation auth for Matrix" by switching to what's ultimately coming anyway
+
+- To help discover (and potentially fix) MAS integration issues with this Ansible playbook
+
+- To help discover (and potentially fix) MAS integration issues with various other Matrix components (bridges, bots, clients, etc.)
+
+- To reap some of the security benefits that Matrix Authentication Service offers, as outlined in the [Better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/) article.
+
+
+## Prerequisites
+
+- ⚠ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
+
+- ⚠ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
+
+- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
+
+
+## Expectations
+
+This section details what you can expect when switching to the Matrix Authentication Service (MAS).
+
+- ❌ **Synapse password providers will need to be disabled**. You can no longer use [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc. When the authentication flow is handled by MAS (not by Synapse anymore), it doesn't make sense to extend the Synapse authentication flow with additional modules. Many bridges used to rely on shared-secret-auth for doing double-puppeting (impersonating other users), but most (at least the mautrix bridges) nowadays use [Appservice Double Puppet](./configuring-playbook-appservice-double-puppet.md) as a better alternative. Older/maintained bridges may still rely on shared-secret-auth, as do other services like [matrix-corporal](./configuring-playbook-matrix-corporal.md).
+
+- ❌ Certain **tools like [synapse-admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. synapse-admin already supports [login with access token](https://github.com/etkecc/synapse-admin/pull/58), browsing users (which Synapse will internally fetch from MAS) and updating user avatars. However, editing users (passwords, etc.) now needs to happen directly against MAS using the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html), which synapse-admin cannot interact with yet.
+
+- ❌ **Some services** (e.g. [Postmoogle](./configuring-playbook-bot-postmoogle.md), but possibly others - the list is yet to be determined) appear to **experience issues when authenticating via MAS**. We're still investigating what breaks and why.
+
+- ⚠ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
+
+- ⚠ **Migrating an existing homeserver to MAS is possible**, but requires **some playbook-assisted manual work** as described in the [Migrating an existing homeserver to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service) section below. **Migration is reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
+
+- ⚠ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
+
+- ⚠ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).
+
+- ⚠ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).
+
+- ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad.
+
+- ✅ Various clients ([Cinny](./configuring-playbook-client-cinny.md), [Element-web](./configuring-playbook-client-element.md), Element X, FluffyChat) will be able to use the **new SSO-based login flow** provided by Matrix Authentication Service
+
+- ✅ The **old login flow** (called `m.login.password`) **will still continue to work**, so clients (old Element, etc.) and bridges/bots that don't support the new OIDC-based login flow will still work. Going through the old login flow does not require users to have a verified email address, as [is the case](https://github.com/element-hq/matrix-authentication-service/issues/1505) for the new SSO-based login flow.
+
+- ✅ [Registering users](./registering-users.md) via **the playbook's `register-user` tag remains unchanged**. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS. Registering users via the command-line is no longer done via the `/matrix/synapse/bin/register` script, but via `/matrix/matrix-authentication-service/bin/register-user`.
+
+- ✅ Users that are prepared by the playbook (for bots, bridges, etc.) will continue to be registered automatically as expected. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS.
+
+
+
+## Installation flows
+
+### New homeserver
+
+For new homeservers (which don't have any users in their Synapse database yet), follow the [Adjusting the playbook configuration](#adjusting-the-playbook-configuration) instructions and then proceed with [Installing](#installing).
+
+### Existing homeserver
+
+Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
+
+For existing Synapse homeservers:
+
+- when following the [Adjusting the playbook configuration](#adjusting-the-playbook-configuration) instructions, make sure to **disable the integration between Synapse and MAS** by **uncommenting** the `matrix_authentication_service_migration_in_progress: true` line as described in the [Marking an existing homeserver for migration](#marking-an-existing-homeserver-for-migration) section below.
+
+- then follow the [Migrating an existing homeserver to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration
+
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_authentication_service_enabled: true
+
+# Generate this encryption secret with: `openssl rand -hex 32`
+matrix_authentication_service_config_secrets_encryption: ''
+
+# When migrating an existing homeserver to Matrix Authentication Service, uncomment the line below.
+# Learn more about the migration process in the "Marking an existing homeserver for migration" section below.
+# For brand-new installations which start directly on MAS, this line can be removed.
+# matrix_authentication_service_migration_in_progress: true
+```
+
+In the sub-sections that follow, we'll cover some additional configuration options that you may wish to adjust.
+
+There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them.
+
+
+### Adjusting the Matrix Authentication Service URL
+
+By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (e.g. https://matrix.example.com/auth). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+By tweaking the `matrix_authentication_service_hostname` and `matrix_authentication_service_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_authentication_service_hostname: auth.example.com
+matrix_authentication_service_path_prefix: /
+```
+
+### Marking an existing homeserver for migration
+
+The [configuration above](#adjusting-the-playbook-configuration) instructs existing users wishing to migrate to add `matrix_authentication_service_migration_in_progress: true` to their configuration.
+
+This is done temporarily. The migration steps are described in more detail in the [Migrating an existing homeserver to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service) section below.
+
+
+### Upstream OAuth2 configuration
+
+To make Matrix Authentication Service delegate to an existing upstream OAuth 2.0/OIDC provider, you can use its [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers).
+
+The playbook exposes a `matrix_authentication_service_config_upstream_oauth2_providers` variable for controlling this setting.
+
+<details>
+<summary>Click to expand the example configuration:</summary>
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_authentication_service_config_upstream_oauth2_providers:
+  - # A unique identifier for the provider
+    # Must be a valid ULID
+    id: 01HFVBY12TMNTYTBV8W921M5FA
+    # The issuer URL, which will be used to discover the provider's configuration.
+    # If discovery is enabled, this *must* exactly match the `issuer` field
+    # advertised in `<issuer>/.well-known/openid-configuration`.
+    issuer: https://example.com/
+    # A human-readable name for the provider,
+    # which will be displayed on the login page
+    #human_name: Example
+    # A brand identifier for the provider, which will be used to display a logo
+    # on the login page. Values supported by the default template are:
+    #  - `apple`
+    #  - `google`
+    #  - `facebook`
+    #  - `github`
+    #  - `gitlab`
+    #  - `twitter`
+    #brand_name: google
+    # The client ID to use to authenticate to the provider
+    client_id: mas-fb3f0c09c4c23de4
+    # The client secret to use to authenticate to the provider
+    # This is only used by the `client_secret_post`, `client_secret_basic`
+    # and `client_secret_jwk` authentication methods
+    #client_secret: f4f6bb68a0269264877e9cb23b1856ab
+    # Which authentication method to use to authenticate to the provider
+    # Supported methods are:
+    #   - `none`
+    #   - `client_secret_basic`
+    #   - `client_secret_post`
+    #   - `client_secret_jwt`
+    #   - `private_key_jwt` (using the keys defined in the `secrets.keys` section)
+    token_endpoint_auth_method: client_secret_post
+    # Which signing algorithm to use to sign the authentication request when using
+    # the `private_key_jwt` or the `client_secret_jwt` authentication methods
+    #token_endpoint_auth_signing_alg: RS256
+    # The scopes to request from the provider
+    # In most cases, it should always include `openid` scope
+    scope: "openid email profile"
+    # How the provider configuration and endpoints should be discovered
+    # Possible values are:
+    #  - `oidc`: discover the provider through OIDC discovery,
+    #     with strict metadata validation (default)
+    #  - `insecure`: discover through OIDC discovery, but skip metadata validation
+    #  - `disabled`: don't discover the provider and use the endpoints below
+    #discovery_mode: oidc
+    # Whether PKCE should be used during the authorization code flow.
+    # Possible values are:
+    #  - `auto`: use PKCE if the provider supports it (default)
+    #    Determined through discovery, and disabled if discovery is disabled
+    #  - `always`: always use PKCE (with the S256 method)
+    #  - `never`: never use PKCE
+    #pkce_method: auto
+    # The provider authorization endpoint
+    # This takes precedence over the discovery mechanism
+    #authorization_endpoint: https://example.com/oauth2/authorize
+    # The provider token endpoint
+    # This takes precedence over the discovery mechanism
+    #token_endpoint: https://example.com/oauth2/token
+    # The provider JWKS URI
+    # This takes precedence over the discovery mechanism
+    #jwks_uri: https://example.com/oauth2/keys
+    # How user attributes should be mapped
+    #
+    # Most of those attributes have two main properties:
+    #   - `action`: what to do with the attribute. Possible values are:
+    #      - `ignore`: ignore the attribute
+    #      - `suggest`: suggest the attribute to the user, but let them opt out
+    #      - `force`: always import the attribute, and don't fail if it's missing
+    #      - `require`: always import the attribute, and fail if it's missing
+    #   - `template`: a Jinja2 template used to generate the value. In this template,
+    #      the `user` variable is available, which contains the user's attributes
+    #      retrieved from the `id_token` given by the upstream provider.
+    #
+    # Each attribute has a default template which follows the well-known OIDC claims.
+    #
+    claims_imports:
+      # The subject is an internal identifier used to link the
+      # user's provider identity to local accounts.
+      # By default it uses the `sub` claim as per the OIDC spec,
+      # which should fit most use cases.
+      subject:
+        #template: "{{ user.sub }}"
+      # The localpart is the local part of the user's Matrix ID.
+      # For example, on the `example.com` server, if the localpart is `alice`,
+      #  the user's Matrix ID will be `@alice:example.com`.
+      localpart:
+        #action: force
+        #template: "{{ user.preferred_username }}"
+      # The display name is the user's display name.
+      displayname:
+        #action: suggest
+        #template: "{{ user.name }}"
+      # An email address to import.
+      email:
+        #action: suggest
+        #template: "{{ user.email }}"
+        # Whether the email address must be marked as verified.
+        # Possible values are:
+        #  - `import`: mark the email address as verified if the upstream provider
+        #     has marked it as verified, using the `email_verified` claim.
+        #     This is the default.
+        #   - `always`: mark the email address as verified
+        #   - `never`: mark the email address as not verified
+        #set_email_verification: import
+```
+</details>
+
+💡 Refer to the [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers) for the most up-to-date schema and example for providers. The value shown above here may be out of date.
+
+⚠ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.
+
+
+## Installing
+
+Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration), you can run the [installation](installing.md) command: `just install-all`
+
+If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing homeserver to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service) guide.
+
+💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly).
+
+
+## Migrating an existing Synapse homeserver to Matrix Authentication Service
+
+Our migration guide is loosely based on the upstream [Migrating an existing homeserver](https://element-hq.github.io/matrix-authentication-service/setup/migration.html) guide.
+
+Migration is done via a tool called `syn2mas`, which the playbook could run for you (in a container).
+
+The installation + migration steps are like this:
+
+1. [Adjust your configuration](#adjusting-the-playbook-configuration) to **disable the integration between the homeserver and MAS**. This is done by **uncommenting** the `matrix_authentication_service_migration_in_progress: true` line.
+
+2. Perform the initial [installation](#installing). At this point:
+
+  - Matrix Authentication Service will be installed. Its database will be empty, so it cannot validate existing access tokens or authentication users yet.
+
+  - The homeserver will still continue to use its local database for validating existing access tokens.
+
+  - Various [compatibility layer URLs](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) are not yet installed. New login sessions will still be forwarded to the homeserver, which is capable of completing them.
+
+3. Consider taking a full [backup of your Postgres database](./maintenance-postgres.md#backing-up-postgresql). This is done just in case. The **syn2mas migration tool does not delete any data**, so it should be possible to revert to your previous setup by merely disabling MAS and re-running the playbook (no need to restore a Postgres backup). However, do note that as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
+
+4. [Migrate your data from Synapse to Matrix Authentication Service using syn2mas](#migrate-your-data-from-synapse-to-matrix-authentication-service-using-syn2mas)
+
+5. [Adjust your configuration](#adjusting-the-playbook-configuration) again, removing the `matrix_authentication_service_migration_in_progress: false` line
+
+5. Perform the [installation](#installing) again. At this point:
+
+  - The homeserver will start delegating authentication to MAS.
+
+  - The compatibility layer URLs will be installed. New login sessions will be completed by MAS.
+
+6. [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)
+
+
+### Migrate your data from Synapse to Matrix Authentication Service using syn2mas
+
+We **don't** ask you to [run the `syn2mas` migration advisor command](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#run-the-migration-advisor), because it only gives you the green light if your Synapse configuration (`homeserver.yaml`) is configured in a way that's compatible with MAS (delegating authentication to MAS; disabling Synapse's password config; etc.). Until we migrate your data with the `syn2mas` tool, we intentionally avoid doing these changes to allow existing user sessions to work.
+
+You can invoke the `syn2mas` tool via the playbook by running the playbook's `matrix-authentication-service-syn2mas` tag. We recommend first doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration).
+
+#### Performing a syn2mas dry-run
+
+We recommend doing a [dry-run](https://en.wikipedia.org/wiki/Dry_run_(testing)) first to verify that everything will work out as expected.
+
+A dry-run would not cause downtime, because it avoids stopping Synapse.
+
+To perform a dry-run, run:
+
+```sh
+just run-tags matrix-authentication-service-syn2mas -e matrix_authentication_service_syn2mas_dry_run=true
+```
+
+Observe the command output (especially the last line of the the syn2mas output). If you are confident that the migration will work out as expected, you can proceed with a [real migration](#performing-a-real-syn2mas-migration).
+
+#### Performing a real syn2mas migration
+
+Before performing a real migration:
+
+- make sure you've familiarized yourself with the [expectations](#expectations)
+
+- make sure you've performed a Postgres backup, just in case
+
+- make sure you're aware of the irreversibility of the migration process without disruption after users have created new login sessions via the new MAS setup
+
+To perform a real migration, run the `matrix-authentication-service-syn2mas` tag **without** the `matrix_authentication_service_syn2mas_dry_run` variable:
+
+```sh
+just run-tags matrix-authentication-service-syn2mas
+```
+
+Having performed a `syn2mas` migration once, trying to do it again will report errors for users that were already migrated (e.g. "Error: Unknown upstream provider oauth-delegated").
+
+
+## Verify that Matrix Authentication Service is installed correctly
+
+After [installation](#installing), run the `doctor` subcommand of the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) to verify that MAS is installed correctly.
+
+You can do it:
+
+- either via the Ansible playbook's `matrix-authentication-service-mas-cli-doctor` tag: `just run-tags matrix-authentication-service-mas-cli-doctor`
+
+- or by running the `mas-cli` script on the server (which invokes the `mas-cli` tool inside a container): `/matrix/matrix-authentication-service/bin/mas-cli doctor`
+
+If successful, you should see some output that looks like this:
+
+```
+💡 Running diagnostics, make sure that both MAS and Synapse are running, and that MAS is using the same configuration files as this tool.
+✅ Matrix client well-known at "https://example.com/.well-known/matrix/client" is valid
+✅ Homeserver is reachable at "http://matrix-synapse:8008/_matrix/client/versions"
+✅ Homeserver at "http://matrix-synapse:8008/_matrix/client/v3/account/whoami" is reachable, and it correctly rejected an invalid token.
+✅ The Synapse admin API is reachable at "http://matrix-synapse:8008/_synapse/admin/v1/server_version".
+✅ The Synapse admin API is reachable with authentication at "http://matrix-synapse:8008/_synapse/admin/v1/background_updates/status".
+✅ The legacy login API at "https://matrix.example.com/_matrix/client/v3/login" is reachable and is handled by MAS.
+```
+
+## Management
+
+You can use the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) (exposed via the `/matrix/matrix-authentication-service/bin/mas-cli` script) to perform administrative tasks against MAS.
+
+This documentation page already mentions:
+
+- the `mas-cli doctor` sub-command in the [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly) section, which you can run via the CLI and via the Ansible playbook's `matrix-authentication-service-mas-cli-doctor` tag
+
+- the `mas-cli manage register-user` sub-command in the [Registering users](./registering-users.md) documentation
+
+There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
+
+
+## User registration
+
+After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
+
+You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
+
+
+## Working around email deliverability issues
+
+Because Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working.
+
+Matrix Authentication Service attempts to verify email addresses by sending a verification email to the address specified by the user whenever they log in to an account without a verified email address.
+
+If email delivery is not working, **you can retrieve the email configuration code from the Matrix Authentication Service's logs** (`journalctl -fu matrix-authentication-service`).
+
+Alternatively, you can use the [`mas-cli` management tool](#management) to manually verify email addresses for users. Example: `/matrix/matrix-authentication-service/bin/mas-cli manage verify-email some.username email@example.com`

docs/configuring-playbook-s3-goofys.md

@@ -59,9 +59,9 @@ matrix_s3_media_store_path: /matrix/s3-media-store
 
 This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
 
-5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+4. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
 
-6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
+5. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
 
 ```sh
 sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
@@ -69,27 +69,27 @@ sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/stora
 
 You may need to install `rsync` manually.
 
-7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
+6. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
 
-8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
+7. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
 
-9. Sync the files again by re-running the `rsync` command you see in step #6
+8. Sync the files again by re-running the `rsync` command you see in step #6
 
-10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
+9. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
 
-11. Get the old media store out of the way by running this command on the server:
+10. Get the old media store out of the way by running this command on the server:
 
 ```sh
 mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
 ```
 
-12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
+11. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
 
-13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+12. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
 
-14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
+13. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
 
-15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
+14. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
 
 
 ### Migrating to Backblaze B2

docs/configuring-playbook-synapse-admin.md

@@ -22,6 +22,8 @@ matrix_synapse_admin_enabled: true
 
 By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) - the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable.
 
+⚠ **Warning**: If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all.
+
 
 ## Installing
 

docs/configuring-playbook-synapse.md

@@ -88,6 +88,8 @@ Certain Synapse administration tasks (managing users and rooms, etc.) can be per
 
 ## Synapse + OpenID Connect for Single-Sign-On
 
+💡 An alternative to setting up OIDC in Synapse is to use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS). Newer clients (like Element X) only support SSO-based authentication via MAS and not via the legacy Synapse OIDC setup described below. That said, MAS is still a new experimental service which comes with its own downsides. Consult its documentation to learn if it will be a good fit for your deployment.
+
 If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional configuration.
 
 This example configuration is for [keycloak](https://www.keycloak.org/), an opensource Identity Provider maintained by Red Hat.

docs/configuring-playbook.md

@@ -90,6 +90,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 ### Authentication and user-related
 
+- [Setting up Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) (Next-generation auth for Matrix, based on OAuth 2.0/OIDC) (optional)
+
 - [Setting up Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) (optional)
 
 - [Setting up an ma1sd Identity Server](configuring-playbook-ma1sd.md) (optional)

docs/configuring-well-known.md

@@ -180,7 +180,7 @@ backend matrix-backend
 **For AWS CloudFront**
 
    1. Add a custom origin with matrix.example.com to your distribution
-   1. Add two behaviors, one for `.well-known/matrix/client` and one for `.well-known/matrix/server` and point them to your new origin.
+   2. Add two behaviors, one for `.well-known/matrix/client` and one for `.well-known/matrix/server` and point them to your new origin.
 
 Make sure to:
 

docs/obtaining-access-tokens.md

@@ -13,10 +13,10 @@ Below, we describe 2 ways to generate an access token for a user - using [Elemen
 ## Obtain an access token via Element
 
 1. In a private browsing session (incognito window), open Element.
-1. Log in with the user's credentials.
-1. In the settings page, choose "Help & About", scroll down to the bottom and expand the `Access Token` section (see screenshot below).
-1. Copy the access token to your configuration.
-1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
+2. Log in with the user's credentials.
+3. In the settings page, choose "Help & About", scroll down to the bottom and expand the `Access Token` section (see screenshot below).
+4. Copy the access token to your configuration.
+5. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
 
 ![Obtaining an access token with Element](assets/obtain_admin_access_token_element.png)
 

docs/registering-users.md

@@ -14,7 +14,15 @@ Table of contents:
 
 ## Registering users manually
 
-You can do it via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
+**Note**: in the commands below, `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
+
+After registering a user (using one of the methods below), **you can log in with that user** via the [Element](configuring-playbook-client-element.md) service that this playbook has installed for you at a URL like this: `https://element.example.com/`.
+
+### Registering users via the Ansible playbook
+
+It's best to register users via the Ansible playbook, because it works regardless of homeserver implementation (Synapse, Dendrite, etc) or usage of [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) (MAS).
+
+To register a user via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
 
 ```sh
 just register-user <your-username> <your-password> <admin access: yes or no>
@@ -26,27 +34,63 @@ just register-user <your-username> <your-password> <admin access: yes or no>
 
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
+
+# Example: `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user`
 ```
 
-**or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
+⚠ **Warning**: If you're registering users against Matrix Authentication Service, do note that it [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
+
+### Registering users manually for Synapse
+
+If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default), you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
 
 ```sh
 /matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
+
+# Example: `/matrix/synapse/bin/register-user john secret-password 1`
 ```
 
-**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
+### Registering users manually for Dendrite
 
-**You can then log in with that user** via the Element service that this playbook has created for you at a URL like this: `https://element.example.com/`.
+If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver implementation, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
 
------
+```sh
+/matrix/dendrite/bin/create-account <your-username> <your-password> <admin access: 0 or 1>
 
-If you've just installed Matrix, **to finalize the installation process**, it's best if you proceed to [Configuring service discovery via .well-known](configuring-well-known.md)
+# Example: `/matrix/dendrite/bin/create-account john secret-password 1`
+```
+
+### Registering users manually for Matrix Authentication Service
+
+If you're using the [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) and your existing homeserver (most likely [Synapse](./configuring-playbook-synapse.md)) is delegating authentication to it, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
+
+```sh
+/matrix/matrix-authentication-service/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
+
+# Example: `/matrix/matrix-authentication-service/bin/register-user john secret-password 1`
+```
+
+This `register-user` script actually invokes the `mas-cli manage register-user` command under the hood.
+If you'd like more control over the registration process, consider invoking the `mas-cli` command directly:
+
+```sh
+/matrix/matrix-authentication-service/bin/mas-cli manage register-user --help
+```
+
+⚠ **Warning**: Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
+
+
+## Things to do after registering users
+
+If you've just installed Matrix and created some users, **to finalize the installation process** it's best if you proceed with [Configuring service discovery via .well-known](configuring-well-known.md)
 
 
 ## Managing users via a Web UI
 
 To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).
 
+⚠ **Warning**: If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information.
+
 
 ## Letting certain users register on your private server
 
@@ -66,9 +110,11 @@ and running the [installation](installing.md) procedure once again.
 If you're opening up registrations publicly like this, you might also wish to [configure CAPTCHA protection](configuring-captcha.md).
 
 
-## Adding/Removing Administrator privileges to an existing Synapse user
+## Adding/Removing Administrator privileges to an existing user
 
-To change the admin privileges for a user, you need to run an SQL query like this against the `synapse` database:
+### Adding/Removing Administrator privileges to an existing user in Synapse
+
+To change the admin privileges for a user in Synapse's local database, you need to run an SQL query like this against the `synapse` database:
 
 ```sql
 UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:example.com';
@@ -87,3 +133,9 @@ If you're using the integrated Postgres server and not an [external Postgres ser
 You can then proceed to run the query above.
 
 **Note**: directly modifying the raw data of Synapse (or any other software) could cause the software to break. You've been warned!
+
+### Adding/Removing Administrator privileges to an existing user in Matrix Authentication Service
+
+Promoting/demoting a user in Matrix Authentication Service cannot currently (2024-10-19) be done via the [`mas-cli` Management tool](./configuring-playbook-matrix-authentication-service.md#management).
+
+You can do it via the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html)'s `POST /api/admin/v1/users/{id}/set-admin` endpoint.

group_vars/matrix_servers

@@ -273,6 +273,8 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': 'matrix-alertmanager-receiver.service', 'priority': 2200, 'groups': ['matrix', 'alertmanager-receiver']}] if matrix_alertmanager_receiver_enabled else [])
     +
+    ([{'name': 'matrix-authentication-service.service', 'priority': 2200, 'groups': ['matrix', 'matrix-authentication-service']}] if matrix_authentication_service_enabled else [])
+    +
     ([{'name': 'matrix-bot-buscarron.service', 'priority': 2200, 'groups': ['matrix', 'bots', 'buscarron', 'bot-buscarron']}] if matrix_bot_buscarron_enabled else [])
     +
     ([{'name': 'matrix-bot-baibot.service', 'priority': 2200, 'groups': ['matrix', 'bots', 'baibot', 'bot-baibot']}] if matrix_bot_baibot_enabled else [])
@@ -615,6 +617,106 @@ matrix_alertmanager_receiver_metrics_proxying_path: "{{ matrix_metrics_exposure_
 ######################################################################
 
 
+######################################################################
+#
+# matrix-authentication-service
+#
+######################################################################
+
+matrix_authentication_service_enabled: false
+
+matrix_authentication_service_hostname: "{{ matrix_server_fqn_matrix }}"
+matrix_authentication_service_path_prefix: /auth
+
+matrix_authentication_service_config_database_host: "{{ postgres_connection_hostname if postgres_enabled else '' }}"
+matrix_authentication_service_config_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'mas.db', rounds=655555) | to_uuid }}"
+
+matrix_authentication_service_config_matrix_homeserver: "{{ matrix_domain }}"
+matrix_authentication_service_config_matrix_secret: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'mas.hs.secret', rounds=655555) | to_uuid }}"
+matrix_authentication_service_config_matrix_endpoint: "{{ matrix_homeserver_container_url }}"
+
+# We're using a non-default configuration which:
+# - allows passwords from Synapse (hashed with bcrypt) to be imported with scheme version 1 so existing users will be able to login
+# - as soon as they do one login, the hash will be 'upgraded' to argon2id
+matrix_authentication_service_config_passwords_schemes:
+  - version: 1
+    secret: "{{ matrix_synapse_password_config_pepper }}"
+    algorithm: bcrypt
+  - version: 2
+    algorithm: argon2id
+
+matrix_authentication_service_config_clients_auto: |-
+  {{
+    ([
+      {
+        'client_id': matrix_synapse_experimental_features_msc3861_client_id,
+        'client_auth_method': matrix_synapse_experimental_features_msc3861_client_auth_method,
+        'client_secret': matrix_synapse_experimental_features_msc3861_client_secret,
+      }
+    ] if matrix_synapse_experimental_features_msc3861_enabled else [])
+  }}
+
+matrix_authentication_service_config_email_transport: "{{ 'smtp' if exim_relay_enabled else 'blackhole' }}"
+matrix_authentication_service_config_email_hostname: "{{ exim_relay_identifier if exim_relay_enabled else '' }}"
+matrix_authentication_service_config_email_port: "{{ 8025 if exim_relay_enabled else 587 }}"
+matrix_authentication_service_config_email_mode: "{{ 'plain' if exim_relay_enabled else 'starttls' }}"
+matrix_authentication_service_config_email_from_address: "{{ exim_relay_sender_address }}"
+
+matrix_authentication_service_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
+
+matrix_authentication_service_container_network: "{{ matrix_homeserver_container_network }}"
+
+matrix_authentication_service_container_additional_networks_auto: |-
+  {{
+    (
+      ([postgres_container_network] if postgres_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname else [])
+      +
+      ([exim_relay_container_network] if (exim_relay_enabled and matrix_authentication_service_config_email_transport == 'smtp' and matrix_authentication_service_config_email_hostname == exim_relay_identifier and matrix_authentication_service_container_network != exim_relay_container_network) else [])
+      +
+      ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network and matrix_authentication_service_container_labels_traefik_enabled else [])
+    ) | unique
+  }}
+
+matrix_authentication_service_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_authentication_service_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_authentication_service_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_authentication_service_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+matrix_authentication_service_container_labels_public_compatibility_layer_enabled: "{{ not matrix_authentication_service_migration_in_progress}}"
+matrix_authentication_service_container_labels_public_compatibility_layer_hostname: "{{ matrix_server_fqn_matrix }}"
+
+matrix_authentication_service_container_labels_internal_compatibility_layer_enabled: "{{ not matrix_authentication_service_migration_in_progress}}"
+matrix_authentication_service_container_labels_internal_compatibility_layer_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
+
+# MAS somewhat depends on the homeserver service, but the homeserver also depends on MAS.
+# To avoid a circular dependency, we make MAS not depend on the homeserver here.
+# The homeserver is more lost without MAS than MAS is without the homeserver, so we'll define the dependency on the homeserver side.
+# We'll put our dependency on the homeserver as a "want", rather than a requirement.
+matrix_authentication_service_systemd_required_services_list_auto: |
+  {{
+    ([postgres_identifier ~ '.service'] if postgres_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname else [])
+  }}
+
+# See more information about this homeserver "want" in the comment for `matrix_authentication_service_systemd_required_services_list_auto` above.
+matrix_authentication_service_systemd_wanted_services_list_auto: |
+  {{
+    ['matrix-' + matrix_homeserver_implementation + '.service']
+    +
+    ([exim_relay_identifier ~ '.service'] if (exim_relay_enabled and matrix_authentication_service_config_email_transport == 'smtp' and matrix_authentication_service_config_email_hostname == exim_relay_identifier and matrix_authentication_service_container_network != exim_relay_container_network) else [])
+  }}
+
+matrix_authentication_service_syn2mas_container_network: "{{ postgres_container_network if postgres_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname else matrix_authentication_service_container_network }}"
+
+matrix_authentication_service_syn2mas_synapse_homeserver_config_path: "{{ matrix_synapse_config_dir_path + '/homeserver.yaml' if matrix_synapse_enabled else '' }}"
+
+######################################################################
+#
+# /matrix-authentication-service
+#
+######################################################################
+
+
+
 
 ######################################################################
 #
@@ -3921,6 +4023,12 @@ postgres_managed_databases_auto: |
       'password': matrix_dendrite_database_password,
     }] if (matrix_dendrite_enabled and matrix_dendrite_database_hostname == postgres_connection_hostname) else [])
     +
+    ([{
+      'name': matrix_authentication_service_config_database_database,
+      'username': matrix_authentication_service_config_database_username,
+      'password': matrix_authentication_service_config_database_password,
+    }] if (matrix_authentication_service_config_database_host == postgres_connection_hostname) else [])
+    +
     ([{
       'name': matrix_sliding_sync_database_name,
       'username': matrix_sliding_sync_database_username,
@@ -4632,6 +4740,8 @@ matrix_synapse_systemd_required_services_list_auto: |
     ([keydb_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else [])
     +
     (['matrix-goofys.service'] if matrix_s3_media_store_enabled else [])
+    +
+    (['matrix-authentication-service.service'] if (matrix_authentication_service_enabled and matrix_synapse_experimental_features_msc3861_enabled) else [])
   }}
 
 matrix_synapse_systemd_wanted_services_list_auto: |
@@ -4656,6 +4766,20 @@ matrix_synapse_ext_media_repo_enabled: "{{ matrix_media_repo_enabled }}"
 matrix_synapse_report_stats: "{{ matrix_synapse_usage_exporter_enabled }}"
 matrix_synapse_report_stats_endpoint: "http://{{ matrix_synapse_usage_exporter_identifier }}:{{ matrix_synapse_usage_exporter_container_port | string }}/report-usage-stats/push"
 
+matrix_synapse_experimental_features_msc3861_enabled: "{{ matrix_authentication_service_enabled and not matrix_authentication_service_migration_in_progress }}"
+matrix_synapse_experimental_features_msc3861_issuer: "{{ matrix_authentication_service_http_base_container_url if matrix_authentication_service_enabled else '' }}"
+matrix_synapse_experimental_features_msc3861_client_secret: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'syn.ngauth.cs', rounds=655555) | to_uuid }}"
+matrix_synapse_experimental_features_msc3861_admin_token: "{{ matrix_authentication_service_config_matrix_secret if matrix_authentication_service_enabled else '' }}"
+matrix_synapse_experimental_features_msc3861_account_management_url: "{{ matrix_authentication_service_account_management_url if matrix_authentication_service_enabled else '' }}"
+
+# Disable password authentication when delegating authentication to Matrix Authentication Service.
+# Unless this is done, Synapse fails on startup with:
+# > Error in configuration at 'password_config.enabled':
+# > Password auth cannot be enabled when OAuth delegation is enabled
+matrix_synapse_password_config_enabled: "{{ not matrix_synapse_experimental_features_msc3861_enabled }}"
+
+matrix_synapse_register_user_script_matrix_authentication_service_path: "{{ matrix_authentication_service_bin_path }}/register-user"
+
 ######################################################################
 #
 # /matrix-synapse
@@ -5754,6 +5878,10 @@ matrix_static_files_file_matrix_client_property_io_element_jitsi_preferred_domai
 
 matrix_static_files_file_matrix_client_property_org_matrix_msc3575_proxy_url: "{{ matrix_homeserver_sliding_sync_url }}"
 
+matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_enabled: "{{ matrix_authentication_service_enabled }}"
+matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_issuer: "{{ matrix_authentication_service_config_http_issuer if matrix_authentication_service_enabled else '' }}"
+matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_account: "{{ matrix_authentication_service_account_management_url }}"
+
 matrix_static_files_file_matrix_client_property_m_tile_server_entries_enabled: "{{ matrix_client_element_location_sharing_enabled }}"
 matrix_static_files_file_matrix_client_property_m_tile_server_map_style_url: "{{ ('https://' if matrix_playbook_ssl_enabled else 'http://') + matrix_server_fqn_element }}/map_style.json"
 

roles/custom/matrix-authentication-service/defaults/main.yml

@@ -0,0 +1,595 @@
+---
+
+# matrix-authentication-service (MAS) is an OAuth 2.0 and OpenID Provider server for Matrix.
+# Project source code URL: https://github.com/element-hq/matrix-authentication-service
+
+matrix_authentication_service_enabled: true
+
+matrix_authentication_service_hostname: ''
+
+# Controls the path prefix for the authentication service.
+# This value must either be `/` or not end with a slash (e.g. `/auth`).
+matrix_authentication_service_path_prefix: /
+
+matrix_authentication_service_container_image_self_build: false
+matrix_authentication_service_container_repo: "https://github.com/element-hq/matrix-authentication-service.git"
+matrix_authentication_service_container_repo_version: "{{ 'main' if matrix_authentication_service_version == 'latest' else ('v' + matrix_authentication_service_version) }}"
+matrix_authentication_service_container_src_files_path: "{{ matrix_base_data_path }}/matrix-authentication-service/container-src"
+
+# renovate: datasource=docker depName=ghcr.io/element-hq/matrix-authentication-service
+matrix_authentication_service_version: 0.12.0
+matrix_authentication_service_container_image: "{{ matrix_authentication_service_container_image_name_prefix }}element-hq/matrix-authentication-service:{{ matrix_authentication_service_version }}"
+matrix_authentication_service_container_image_name_prefix: "{{ 'localhost/' if matrix_authentication_service_container_image_self_build else 'ghcr.io/' }}"
+matrix_authentication_service_container_image_force_pull: "{{ matrix_authentication_service_container_image.endswith(':latest') }}"
+
+matrix_authentication_service_base_path: "{{ matrix_base_data_path }}/matrix-authentication-service"
+matrix_authentication_service_bin_path: "{{ matrix_authentication_service_base_path }}/bin"
+matrix_authentication_service_config_path: "{{ matrix_authentication_service_base_path }}/config"
+matrix_authentication_service_data_path: "{{ matrix_authentication_service_base_path }}/data"
+matrix_authentication_service_data_keys_path: "{{ matrix_authentication_service_data_path }}/keys"
+
+matrix_authentication_service_uid: "{{ matrix_user_uid }}"
+matrix_authentication_service_gid: "{{ matrix_user_gid }}"
+
+matrix_authentication_service_container_network: ""
+
+matrix_authentication_service_container_additional_networks: "{{ matrix_authentication_service_container_additional_networks_auto + matrix_authentication_service_container_additional_networks_custom }}"
+matrix_authentication_service_container_additional_networks_auto: []
+matrix_authentication_service_container_additional_networks_custom: []
+
+# A list of extra arguments to pass to the container
+matrix_authentication_service_container_extra_arguments: []
+
+# List of systemd services that matrix-authentication-service.service depends on
+matrix_authentication_service_systemd_required_services_list: "{{ matrix_authentication_service_systemd_required_services_list_default + matrix_authentication_service_systemd_required_services_list_auto + matrix_authentication_service_systemd_required_services_list_custom }}"
+matrix_authentication_service_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+matrix_authentication_service_systemd_required_services_list_auto: []
+matrix_authentication_service_systemd_required_services_list_custom: []
+
+# List of systemd services that matrix-authentication-service.service wants
+matrix_authentication_service_systemd_wanted_services_list: "{{ matrix_authentication_service_systemd_wanted_services_list_auto + matrix_authentication_service_systemd_wanted_services_list_custom }}"
+matrix_authentication_service_systemd_wanted_services_list_auto: []
+matrix_authentication_service_systemd_wanted_services_list_custom: []
+
+########################################################################################
+#                                                                                      #
+# Key management                                                                       #
+#                                                                                      #
+########################################################################################
+
+# Controls whether the playbook will manage the secrets keys for you.
+#
+# See:
+# - matrix_authentication_service_config_secrets_keys
+# - matrix_authentication_service_key_management_*
+matrix_authentication_service_key_management_enabled: true
+
+matrix_authentication_service_key_management_list: "{{ matrix_authentication_service_key_management_list_default + matrix_authentication_service_key_management_list_custom }}"
+matrix_authentication_service_key_management_list_default: |-
+  {{
+    (
+      ([
+        {
+          "config": {
+            "kid": matrix_authentication_service_key_management_rsa_2048_key_id,
+            "key_file": ("/keys/" + matrix_authentication_service_key_management_rsa_2048_key_file),
+          },
+          "key_file": matrix_authentication_service_key_management_rsa_2048_key_file,
+          "generation_command": matrix_authentication_service_key_management_rsa_2048_generation_command,
+        }
+      ] if matrix_authentication_service_key_management_rsa_2048_enabled else [])
+      +
+      ([
+        {
+          "config": {
+            "kid": matrix_authentication_service_key_management_ecdsa_p256_key_id,
+            "key_file": ("/keys/" + matrix_authentication_service_key_management_ecdsa_p256_key_file),
+          },
+          "key_file": matrix_authentication_service_key_management_ecdsa_p256_key_file,
+          "generation_command": matrix_authentication_service_key_management_ecdsa_p256_generation_command,
+        }
+      ] if matrix_authentication_service_key_management_ecdsa_p256_enabled else [])
+      +
+      ([
+        {
+          "config": {
+            "kid": matrix_authentication_service_key_management_ecdsa_p384_key_id,
+            "key_file": ("/keys/" + matrix_authentication_service_key_management_ecdsa_p384_key_file),
+          },
+          "key_file": matrix_authentication_service_key_management_ecdsa_p384_key_file,
+          "generation_command": matrix_authentication_service_key_management_ecdsa_p384_generation_command,
+        }
+      ] if matrix_authentication_service_key_management_ecdsa_p384_enabled else [])
+      +
+      ([
+        {
+          "config": {
+            "kid": matrix_authentication_service_key_management_ecdsa_k256_key_id,
+            "key_file": ("/keys/" + matrix_authentication_service_key_management_ecdsa_k256_key_file),
+          },
+          "key_file": matrix_authentication_service_key_management_ecdsa_k256_key_file,
+          "generation_command": matrix_authentication_service_key_management_ecdsa_k256_generation_command,
+        }
+      ] if matrix_authentication_service_key_management_ecdsa_k256_enabled else [])
+    )
+    if matrix_authentication_service_key_management_enabled
+    else []
+  }}
+matrix_authentication_service_key_management_list_custom: []
+
+matrix_authentication_service_key_management_rsa_2048_enabled: true
+matrix_authentication_service_key_management_rsa_2048_key_id: default-rsa
+matrix_authentication_service_key_management_rsa_2048_key_file: rsa-2048.priv.pem
+matrix_authentication_service_key_management_rsa_2048_generation_command: "openssl genpkey -algorithm RSA -out __KEY_FILE_PATH__ -pkeyopt rsa_keygen_bits:2048"
+
+matrix_authentication_service_key_management_ecdsa_p256_enabled: true
+matrix_authentication_service_key_management_ecdsa_p256_key_id: default-ecdsa-p256
+matrix_authentication_service_key_management_ecdsa_p256_key_file: ecdsa-p256.priv.pem
+matrix_authentication_service_key_management_ecdsa_p256_generation_command: "openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 -out __KEY_FILE_PATH__ -outform PEM"
+matrix_authentication_service_key_management_ecdsa_p384_enabled: true
+matrix_authentication_service_key_management_ecdsa_p384_key_id: default-ecdsa-p384
+matrix_authentication_service_key_management_ecdsa_p384_key_file: ecdsa-p384.priv.pem
+matrix_authentication_service_key_management_ecdsa_p384_generation_command: "openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:secp384r1 -out __KEY_FILE_PATH__ -outform PEM"
+
+matrix_authentication_service_key_management_ecdsa_k256_enabled: true
+matrix_authentication_service_key_management_ecdsa_k256_key_id: default-ecdsa-k256
+matrix_authentication_service_key_management_ecdsa_k256_key_file: ecdsa-k256.priv.pem
+matrix_authentication_service_key_management_ecdsa_k256_generation_command: "openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:secp256k1 -out __KEY_FILE_PATH__ -outform PEM"
+
+########################################################################################
+#                                                                                      #
+# /Key management                                                                      #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Email configuration                                                                  #
+#                                                                                      #
+########################################################################################
+
+# Controls the `email.from` configuration setting.
+matrix_authentication_service_config_email_from: '"{{ matrix_authentication_service_config_email_from_name }}" <{{ matrix_authentication_service_config_email_from_address }}>'
+matrix_authentication_service_config_email_from_name: 'Matrix Authentication Service'
+matrix_authentication_service_config_email_from_address: "matrix@{{ matrix_domain }}"
+
+# Controls the `email.reply_to` configuration setting.
+matrix_authentication_service_config_email_reply_to: '"{{ matrix_authentication_service_config_email_reply_to_name }}" <{{ matrix_authentication_service_config_email_reply_to_address }}>'
+matrix_authentication_service_config_email_reply_to_name: "{{ matrix_authentication_service_config_email_from_name }}"
+matrix_authentication_service_config_email_reply_to_address: "{{ matrix_authentication_service_config_email_from_address }}"
+
+# Controls the `email.transport` configuration setting.
+#
+# Valid options are: blackhole, smtp, aws_ses
+# Upstream reports that `sendmail` is supported as well,
+# but this is not true when running it in a container image due to the `sendmail` binary not being included.
+matrix_authentication_service_config_email_transport: blackhole
+
+# Controls the `email.mode` configuration setting for SMTP.
+# Options are 'plain', 'tls', or 'starttls'.
+matrix_authentication_service_config_email_mode: plain
+
+# Controls the `email.hostname` configuration setting for SMTP.
+matrix_authentication_service_config_email_hostname: ""
+
+# Controls the `email.port` configuration setting for SMTP.
+matrix_authentication_service_config_email_port: 587
+
+# Controls the `email.username` configuration setting for SMTP.
+matrix_authentication_service_config_email_username: ""
+
+# Controls the `email.password` configuration setting for SMTP.
+matrix_authentication_service_config_email_password: ""
+
+########################################################################################
+#                                                                                      #
+# /Email configuration                                                                 #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Account configuration                                                                #
+#                                                                                      #
+########################################################################################
+
+# Controls the `account.email_change_allowed` configuration setting.
+#
+# Whether users are allowed to change their email addresses.
+matrix_authentication_service_config_account_email_change_allowed: true
+
+# Controls the `account.displayname_change_allowed` configuration setting.
+#
+# Whether users are allowed to change their display names.
+# This should be in sync with the policy in the homeserver configuration.
+matrix_authentication_service_config_account_displayname_change_allowed: true
+
+# Controls the `account.password_registration_enabled` configuration setting.
+#
+# Whether to enable self-service password registration.
+# This has no effect if password login is disabled.
+matrix_authentication_service_config_account_password_registration_enabled: false
+
+# Controls the `account.password_change_allowed` configuration setting.
+#
+# Whether users are allowed to change their passwords.
+# This has no effect if password login is disabled.
+matrix_authentication_service_config_account_password_change_allowed: true
+
+# Controls the `account.password_recovery_enabled` configuration setting.
+#
+# Whether email-based password recovery is enabled
+# This has no effect if password login is disabled.
+matrix_authentication_service_config_account_password_recovery_enabled: false
+
+########################################################################################
+#                                                                                      #
+# /Account configuration                                                               #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Database configuration                                                               #
+#                                                                                      #
+########################################################################################
+
+# Controls the `database.username` configuration setting.
+matrix_authentication_service_config_database_username: 'matrix_authentication_service'
+
+# Controls the `database.password` configuration setting.
+matrix_authentication_service_config_database_password: ''
+
+# Controls the `database.host` configuration setting.
+matrix_authentication_service_config_database_host: ''
+
+# Controls the `database.port` configuration setting.
+matrix_authentication_service_config_database_port: 5432
+
+# Controls the `database.database` configuration setting.
+matrix_authentication_service_config_database_database: 'matrix_authentication_service'
+
+# Controls the `database.ssl_mode` configuration setting.
+matrix_authentication_service_config_database_ssl_mode: disable
+
+# Controls the `database.max_connections` configuration setting.
+matrix_authentication_service_config_database_max_connections: 10
+
+# Controls the `database.min_connections` configuration setting.
+matrix_authentication_service_config_database_min_connections: 0
+
+# Controls the `database.connect_timeout` configuration setting.
+matrix_authentication_service_config_database_connect_timeout: 30
+
+# Controls the `database.idle_timeout` configuration setting.
+matrix_authentication_service_config_database_idle_timeout: 600
+
+# Controls the `database.max_lifetime` configuration setting.
+matrix_authentication_service_config_database_max_lifetime: 1800
+
+########################################################################################
+#                                                                                      #
+# /Database configuration                                                              #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Secrets configuration                                                                #
+#                                                                                      #
+########################################################################################
+
+# Controls the `secrets.encryption` configuration setting.
+matrix_authentication_service_config_secrets_encryption: ''
+
+# Controls the `secrets.keys` configuration setting.
+matrix_authentication_service_config_secrets_keys: |-
+  {{
+    matrix_authentication_service_key_management_list | map(attribute='config') | list
+    if matrix_authentication_service_key_management_enabled
+    else []
+  }}
+
+########################################################################################
+#                                                                                      #
+# /Secrets configuration                                                               #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# HTTP configuration                                                                 #
+#                                                                                      #
+########################################################################################
+
+# Controls the `http.public_base` configuration setting.
+matrix_authentication_service_config_http_public_base: "https://{{ matrix_authentication_service_hostname }}{{ '/' if matrix_authentication_service_path_prefix == '/' else (matrix_authentication_service_path_prefix + '/') }}"
+
+# Controls the `http.issuer` configuration setting.
+matrix_authentication_service_config_http_issuer: "{{ matrix_authentication_service_config_http_public_base }}"
+
+# Controls the `http.trusted_proxies` configuration setting.
+matrix_authentication_service_config_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
+
+########################################################################################
+#                                                                                      #
+# /HTTP configuration                                                                  #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Matrix configuration                                                                 #
+#                                                                                      #
+########################################################################################
+
+# Controls the `matrix.homeserver` configuration setting.
+# The homeserver name, as per the `server_name` in the Synapse configuration file.
+matrix_authentication_service_config_matrix_homeserver: ""
+
+# Controls the `matrix.endpoint` configuration setting.
+# URL to which the homeserver is accessible from the service
+matrix_authentication_service_config_matrix_endpoint: ""
+
+# Controls the `matrix.secret` configuration setting.
+matrix_authentication_service_config_matrix_secret: ""
+
+########################################################################################
+#                                                                                      #
+# /Matrix configuration                                                                #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Passwords configuration                                                              #
+#                                                                                      #
+########################################################################################
+
+# Controls the `passwords.enabled` configuration setting.
+# Whether to enable the password database.
+# If disabled, users will only be able to log in using upstream OIDC providers
+matrix_authentication_service_config_passwords_enabled: true
+
+# Controls the `passwords.schemes` configuration setting.
+# List of password hashing schemes being used.
+# Only change this if you know what you're doing
+matrix_authentication_service_config_passwords_schemes:
+  - version: 1
+    algorithm: argon2id
+
+# Controls the `passwords.minimum_complexity` configuration setting.
+# 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
+matrix_authentication_service_config_passwords_minimum_complexity: 3
+
+########################################################################################
+#                                                                                      #
+# /Passwords configuration                                                             #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Clients configuration                                                                #
+#                                                                                      #
+########################################################################################
+
+# Controls the `clients` configuration setting.
+# List of clients to be used by the authentication service.
+#
+# See:
+# - https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#clients
+# - https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#provision-a-client-for-the-homeserver-to-use
+#
+# To define your own, use `matrix_authentication_service_config_clients_custom`.
+matrix_authentication_service_config_clients: "{{ matrix_authentication_service_config_clients_auto + matrix_authentication_service_config_clients_custom }}"
+matrix_authentication_service_config_clients_auto: []
+matrix_authentication_service_config_clients_custom: []
+
+########################################################################################
+#                                                                                      #
+# /Clients configuration                                                               #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Upstream OAuth2 configuration                                                        #
+#                                                                                      #
+########################################################################################
+
+# Controls the `upstream_oauth2.providers` configuration setting.
+# See:
+# - https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers
+matrix_authentication_service_config_upstream_oauth2_providers: []
+
+########################################################################################
+#                                                                                      #
+# /Upstream OAuth2 configuration                                                       #
+#                                                                                      #
+########################################################################################
+
+
+# Holds the final Matrix Authentication Service configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_authentication_service_configuration_yaml` or `matrix_authentication_service_configuration_extension_yaml`.
+matrix_authentication_service_configuration: "{{ matrix_authentication_service_configuration_yaml | from_yaml | combine(matrix_authentication_service_configuration_extension, recursive=True) }}"
+
+# Default Matrix Authentication Service configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrix_authentication_service_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_authentication_service_configuration_yaml: "{{ lookup('template', 'templates/config.yaml.j2') }}"
+
+matrix_authentication_service_configuration_extension_yaml: |
+  # Your custom YAML configuration for Matrix Authentication Service goes here.
+  # This configuration extends the default starting configuration (`matrix_authentication_service_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_authentication_service_configuration_yaml`.
+  #
+  # Example configuration extension follows:
+  #
+  # user:
+  #   password: something
+
+matrix_authentication_service_configuration_extension: "{{ matrix_authentication_service_configuration_extension_yaml | from_yaml if matrix_authentication_service_configuration_extension_yaml | from_yaml is mapping else {} }}"
+
+# Additional environment variables to pass to the Matrix Authentication Service container.
+#
+# Environment variables take priority over settings in the configuration file.
+#
+# Example:
+# matrix_authentication_service_environment_variables_extension: |
+#   KEY=value
+matrix_authentication_service_environment_variables_extension: ''
+
+
+########################################################################################
+#                                                                                      #
+# Labels                                                                               #
+#                                                                                      #
+########################################################################################
+
+# matrix_authentication_service_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
+# See `../templates/labels.j2` for details.
+#
+# To inject your own other container labels, see `matrix_authentication_service_container_labels_additional_labels`.
+matrix_authentication_service_container_labels_traefik_enabled: true
+matrix_authentication_service_container_labels_traefik_docker_network: "{{ matrix_authentication_service_container_network }}"
+matrix_authentication_service_container_labels_traefik_entrypoints: web-secure
+matrix_authentication_service_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+
+matrix_authentication_service_container_labels_public_main_hostname: "{{ matrix_authentication_service_hostname }}"
+# The path prefix must either be `/` or not end with a slash (e.g. `/auth`).
+matrix_authentication_service_container_labels_public_main_path_prefix: "{{ matrix_authentication_service_path_prefix }}"
+matrix_authentication_service_container_labels_public_main_rule: "Host(`{{ matrix_authentication_service_container_labels_public_main_hostname }}`){% if matrix_authentication_service_container_labels_public_main_path_prefix != '/' %} && PathPrefix(`{{ matrix_authentication_service_container_labels_public_main_path_prefix }}`){% endif %}"
+matrix_authentication_service_container_labels_public_main_priority: 0
+matrix_authentication_service_container_labels_public_main_entrypoints: "{{ matrix_authentication_service_container_labels_traefik_entrypoints }}"
+matrix_authentication_service_container_labels_public_main_tls: "{{ matrix_authentication_service_container_labels_public_main_entrypoints != 'web' }}"
+matrix_authentication_service_container_labels_public_main_tls_certResolver: "{{ matrix_authentication_service_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added to expose the compatibility layer publicly.
+#
+# 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
+# - /_matrix/client/*/logout
+# - /_matrix/client/*/refresh
+#
+# See:
+# - https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer
+# - https://element-hq.github.io/matrix-authentication-service/setup/reverse-proxy.html#compatibility-layer
+#
+# Regardless of whether this is enabled, it may or may not take effect due to the value of other variables.
+# See `matrix_authentication_service_container_labels_traefik_enabled`
+matrix_authentication_service_container_labels_public_compatibility_layer_enabled: false
+matrix_authentication_service_container_labels_public_compatibility_layer_hostname: ""
+matrix_authentication_service_container_labels_public_compatibility_layer_path_regexp: "^/_matrix/client/(?P<version>([^/]+))/(?P<endpoint>(login|logout|refresh))"
+matrix_authentication_service_container_labels_public_compatibility_layer_rule: "Host(`{{ matrix_authentication_service_container_labels_public_compatibility_layer_hostname }}`) && PathRegexp(`{{ matrix_authentication_service_container_labels_public_compatibility_layer_path_regexp }}`)"
+matrix_authentication_service_container_labels_public_compatibility_layer_priority: 0
+matrix_authentication_service_container_labels_public_compatibility_layer_entrypoints: "{{ matrix_authentication_service_container_labels_traefik_entrypoints }}"
+matrix_authentication_service_container_labels_public_compatibility_layer_tls: "{{ matrix_authentication_service_container_labels_public_compatibility_layer_entrypoints != 'web' }}"
+matrix_authentication_service_container_labels_public_compatibility_layer_tls_certResolver: "{{ matrix_authentication_service_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added to expose the compatibility layer on the internal Traefik entrypoint.
+# This is similar to `matrix_authentication_service_container_labels_public_compatibility_layer_enabled`, but the entrypoint and intent is different.
+# Regardless of whether this is enabled, it may or may not take effect due to the value of other variables.
+# See `matrix_authentication_service_container_labels_traefik_enabled`
+matrix_authentication_service_container_labels_internal_compatibility_layer_enabled: false
+matrix_authentication_service_container_labels_internal_compatibility_layer_path_regexp: "{{ matrix_authentication_service_container_labels_public_compatibility_layer_path_regexp }}"
+matrix_authentication_service_container_labels_internal_compatibility_layer_rule: "PathRegexp(`{{ matrix_authentication_service_container_labels_internal_compatibility_layer_path_regexp }}`)"
+matrix_authentication_service_container_labels_internal_compatibility_layer_priority: 0
+matrix_authentication_service_container_labels_internal_compatibility_layer_entrypoints: ""
+
+# Controls which additional headers to attach to all HTTP responses.
+# To add your own headers, use `matrix_authentication_service_container_labels_traefik_additional_response_headers_custom`
+matrix_authentication_service_container_labels_traefik_additional_response_headers: "{{ matrix_authentication_service_container_labels_traefik_additional_response_headers_auto | combine(matrix_authentication_service_container_labels_traefik_additional_response_headers_custom) }}"
+matrix_authentication_service_container_labels_traefik_additional_response_headers_auto: {}
+matrix_authentication_service_container_labels_traefik_additional_response_headers_custom: {}
+
+# matrix_authentication_service_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
+# See `../templates/labels.j2` for details.
+#
+# Example:
+# matrix_authentication_service_container_labels_additional_labels: |
+#   my.label=1
+#   another.label="here"
+matrix_authentication_service_container_labels_additional_labels: ''
+
+########################################################################################
+#                                                                                      #
+# /Labels                                                                              #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# syn2mas configuration                                                                #
+#                                                                                      #
+########################################################################################
+
+matrix_authentication_service_syn2mas_start_wait_time_seconds: 5
+
+matrix_authentication_service_syn2mas_dry_run: false
+
+# renovate: datasource=docker depName=ghcr.io/element-hq/matrix-authentication-service/syn2mas
+matrix_authentication_service_syn2mas_version: 0.12.0
+matrix_authentication_service_syn2mas_container_image: "{{ matrix_authentication_service_container_image_name_prefix }}element-hq/matrix-authentication-service/syn2mas:{{ matrix_authentication_service_syn2mas_version }}"
+matrix_authentication_service_syn2mas_container_image_name_prefix: "{{ 'localhost/' if matrix_authentication_service_container_image_self_build else 'ghcr.io/' }}"
+matrix_authentication_service_syn2mas_container_image_force_pull: "{{ matrix_authentication_service_syn2mas_container_image.endswith(':latest') }}"
+
+matrix_authentication_service_syn2mas_container_image_self_build: "{{ matrix_authentication_service_container_image_self_build }}"
+
+matrix_authentication_service_syn2mas_container_network: "{{ matrix_authentication_service_container_network }}"
+
+# Path to Synapse's homeserver.yaml configuration file.
+matrix_authentication_service_syn2mas_synapse_homeserver_config_path: ""
+
+########################################################################################
+#                                                                                      #
+# /syn2mas configuration                                                               #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Misc                                                                                 #
+#                                                                                      #
+########################################################################################
+
+# Controls whether a migration from a homeserver user database to Matrix Authentication Service is in progress.
+#
+# When this is set to `true`, the playbook will:
+#
+# - disable the integration between the homeserver and Matrix Authentication Service
+# - avoid setting up the "compatibility layer" (that is, avoid installing container labels that capture login endpoints like `/_matrix/client/*/login`, etc.)
+matrix_authentication_service_migration_in_progress: false
+
+########################################################################################
+#                                                                                      #
+# /Misc                                                                                #
+#                                                                                      #
+########################################################################################

roles/custom/matrix-authentication-service/tasks/install.yml

@@ -0,0 +1,103 @@
+---
+
+- name: Ensure Matrix Authentication Service paths exist
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - {path: "{{ matrix_authentication_service_base_path }}", when: true}
+    - {path: "{{ matrix_authentication_service_bin_path }}", when: true}
+    - {path: "{{ matrix_authentication_service_config_path }}", when: true}
+    - {path: "{{ matrix_authentication_service_data_path }}", when: true}
+    - {path: "{{ matrix_authentication_service_data_keys_path }}", when: true}
+    - {path: "{{ matrix_authentication_service_container_src_files_path }}", when: "{{ matrix_authentication_service_container_image_self_build }}"}
+  when: "item.when | bool"
+
+- when: matrix_authentication_service_key_management_enabled | bool
+  block:
+    - name: Ensure openssl installed
+      ansible.builtin.package:
+        name: openssl
+        state: present
+
+    - name: Prepare private key
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/util/prepare_key.yml"
+      with_items: "{{ matrix_authentication_service_key_management_list }}"
+      loop_control:
+        loop_var: private_key_definition
+
+- name: Ensure Matrix Authentication Service configuration installed
+  ansible.builtin.copy:
+    content: "{{ matrix_authentication_service_configuration | to_nice_yaml(indent=2, width=999999) }}"
+    dest: "{{ matrix_authentication_service_config_path }}/config.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Ensure Matrix Authentication Service support files created
+  ansible.builtin.template:
+    src: "{{ item.src }}"
+    dest: "{{ item.dest }}"
+    mode: "{{ item.mode }}"
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - src: "{{ role_path }}/templates/env.j2"
+      dest: "{{ matrix_authentication_service_config_path }}/env"
+      mode: '0644'
+    - src: "{{ role_path }}/templates/labels.j2"
+      dest: "{{ matrix_authentication_service_config_path }}/labels"
+      mode: '0644'
+    - src: "{{ role_path }}/templates/bin/register-user.j2"
+      dest: "{{ matrix_authentication_service_bin_path }}/register-user"
+      mode: '0755'
+    - src: "{{ role_path }}/templates/bin/mas-cli.j2"
+      dest: "{{ matrix_authentication_service_bin_path }}/mas-cli"
+      mode: '0755'
+
+- name: Ensure Matrix Authentication Service container image is pulled
+  community.docker.docker_image:
+    name: "{{ matrix_authentication_service_container_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_authentication_service_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_authentication_service_container_image_force_pull }}"
+  when: "not matrix_authentication_service_container_image_self_build | bool"
+  register: result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: result is not failed
+
+- when: "matrix_authentication_service_container_image_self_build | bool"
+  block:
+    - name: Ensure Matrix Authentication Service repository is present on self-build
+      ansible.builtin.git:
+        repo: "{{ matrix_authentication_service_container_repo }}"
+        version: "{{ matrix_authentication_service_container_repo_version }}"
+        dest: "{{ matrix_authentication_service_container_src_files_path }}"
+        force: "yes"
+      become: true
+      become_user: "{{ matrix_user_username }}"
+
+    - name: Ensure Matrix Authentication Service container image is built
+      ansible.builtin.command:
+        cmd: |-
+          {{ devture_systemd_docker_base_host_command_docker }} buildx build
+          --tag={{ matrix_authentication_service_container_image }}
+          --file={{ matrix_authentication_service_container_src_files_path }}/Dockerfile
+          {{ matrix_authentication_service_container_src_files_path }}
+      changed_when: true
+
+- name: Ensure Matrix Authentication Service container network is created
+  community.general.docker_network:
+    enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
+    name: "{{ matrix_authentication_service_container_network }}"
+    driver: bridge
+
+- name: Ensure matrix-authentication-service.service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-authentication-service.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-authentication-service.service"
+    mode: 0644

roles/custom/matrix-authentication-service/tasks/main.yml

@@ -0,0 +1,38 @@
+---
+
+- tags:
+    - setup-all
+    - setup-matrix-authentication-service
+    - install-all
+    - install-matrix-authentication-service
+  block:
+    - when: matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"
+
+- tags:
+    - matrix-authentication-service-syn2mas
+  block:
+    - when: matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/syn2mas.yml"
+
+- tags:
+    - matrix-authentication-service-mas-cli-doctor
+  block:
+    - when: matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/mas_cli_doctor.yml"
+
+- tags:
+    - register-user
+  block:
+    - when: matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/register_user.yml"
+
+- tags:
+    - setup-all
+    - setup-matrix-authentication-service
+  block:
+    - when: not matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"

roles/custom/matrix-authentication-service/tasks/mas_cli_doctor.yml

@@ -0,0 +1,32 @@
+---
+
+- name: Ensure Matrix Authentication Service is started
+  ansible.builtin.service:
+    name: matrix-authentication-service
+    state: started
+    daemon_reload: true
+  register: matrix_authentication_service_mas_ensure_started_result
+
+- name: Wait a bit, so that Matrix Authentication Service can start
+  when: matrix_authentication_service_mas_ensure_started_result.changed | bool
+  ansible.builtin.wait_for:
+    timeout: "{{ matrix_authentication_service_syn2mas_start_wait_time_seconds }}"
+  delegate_to: 127.0.0.1
+  become: false
+
+- name: Generate mas-cli doctor command
+  ansible.builtin.set_fact:
+    matrix_authentication_service_mas_cli_doctor_command: >-
+      {{ matrix_authentication_service_bin_path }}/mas-cli doctor
+  tags:
+    - skip_ansible_lint
+
+- name: Run mas-cli doctor
+  ansible.builtin.command:
+    cmd: "{{ matrix_authentication_service_mas_cli_doctor_command }}"
+  register: matrix_authentication_service_mas_cli_doctor_command_result
+  changed_when: matrix_authentication_service_mas_cli_doctor_command_result.rc == 0
+
+- name: Print mas-cli doctor command result
+  ansible.builtin.debug:
+    var: matrix_authentication_service_mas_cli_doctor_command_result

roles/custom/matrix-authentication-service/tasks/register_user.yml

@@ -0,0 +1,34 @@
+---
+
+- name: Fail if playbook called incorrectly
+  ansible.builtin.fail:
+    msg: "The `username` variable needs to be provided to this playbook, via --extra-vars"
+  when: "username is not defined or username == '<your-username>'"
+
+- name: Fail if playbook called incorrectly
+  ansible.builtin.fail:
+    msg: "The `password` variable needs to be provided to this playbook, via --extra-vars"
+  when: "password is not defined or password == '<your-password>'"
+
+- name: Fail if playbook called incorrectly
+  ansible.builtin.fail:
+    msg: "The `admin` variable needs to be provided to this playbook, via --extra-vars"
+  when: "admin is not defined or admin not in ['yes', 'no']"
+
+- name: Ensure Matrix Authentication Service is started
+  ansible.builtin.service:
+    name: matrix-authentication-service
+    state: started
+    daemon_reload: true
+  register: matrix_authentication_service_start_result
+
+- name: Wait a while, so that Matrix Authentication Service can start
+  ansible.builtin.pause:
+    seconds: 7
+  when: matrix_authentication_service_start_result.changed | bool
+
+- name: Register user
+  ansible.builtin.command:
+    cmd: "{{ matrix_authentication_service_bin_path }}/register-user {{ username | quote }} {{ password | quote }} {{ '1' if admin == 'yes' else '0' }}"
+  register: matrix_authentication_service_register_user_result
+  changed_when: matrix_authentication_service_register_user_result.rc == 0

roles/custom/matrix-authentication-service/tasks/syn2mas.yml

@@ -0,0 +1,137 @@
+---
+
+- ansible.builtin.set_fact:
+    matrix_authentication_service_syn2mas_dry_run: "{{ matrix_authentication_service_syn2mas_dry_run | bool }}"
+
+- name: Abort, if not using Synapse
+  when: not matrix_synapse_enabled | bool
+  ansible.builtin.fail:
+    msg: |-
+      You can only use syn2mas to migrate from Synapse to Matrix Authentication Service.
+      Other homeserver implementations are not supported.
+
+- name: Fail if required matrix-authentication-service syn2mas settings not defined
+  ansible.builtin.fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and vars[item.name] | length == 0"
+  with_items:
+    - {'name': 'matrix_authentication_service_syn2mas_synapse_homeserver_config_path', when: true}
+
+- name: Check if Synapse homeserver config file exists
+  ansible.builtin.stat:
+    path: "{{ matrix_authentication_service_syn2mas_synapse_homeserver_config_path }}"
+  register: matrix_authentication_service_syn2mas_synapse_config_stat
+
+- name: Fail if Synapse homeserver config file does not exist
+  ansible.builtin.fail:
+    msg: "The Synapse homeserver config file does not exist at the specified path: {{ matrix_authentication_service_syn2mas_synapse_homeserver_config_path }}"
+  when: not matrix_authentication_service_syn2mas_synapse_config_stat.stat.exists
+
+- name: Ensure Matrix Authentication Service syn2mas container image is pulled
+  community.docker.docker_image:
+    name: "{{ matrix_authentication_service_syn2mas_container_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_authentication_service_syn2mas_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_authentication_service_syn2mas_container_image_force_pull }}"
+  when: "not matrix_authentication_service_syn2mas_container_image_self_build | bool"
+  register: result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: result is not failed
+
+- when: "matrix_authentication_service_syn2mas_container_image_self_build | bool"
+  block:
+    - name: Ensure Matrix Authentication Service repository is present on self-build
+      ansible.builtin.git:
+        repo: "{{ matrix_authentication_service_container_repo }}"
+        version: "{{ matrix_authentication_service_container_repo_version }}"
+        dest: "{{ matrix_authentication_service_container_src_files_path }}"
+        force: "yes"
+      become: true
+      become_user: "{{ matrix_user_username }}"
+      register: matrix_authentication_service_git_pull_results
+
+    - name: Ensure Matrix Authentication Service syn2mas container image is built
+      ansible.builtin.command:
+        cmd: |-
+          {{ devture_systemd_docker_base_host_command_docker }} buildx build
+          --tag={{ matrix_authentication_service_syn2mas_container_image }}
+          --file={{ matrix_authentication_service_container_src_files_path }}/tools/syn2mas/Dockerfile
+          {{ matrix_authentication_service_container_src_files_path }}/tools/syn2mas
+      changed_when: true
+
+- name: Ensure Synapse is stopped
+  when: not matrix_authentication_service_syn2mas_dry_run | bool
+  ansible.builtin.service:
+    name: matrix-synapse
+    state: stopped
+    daemon_reload: true
+  register: matrix_authentication_service_synapse_ensure_stopped_result
+
+# We probably don't necessarily need to stop this, because:
+# - the upstream docs don't say we should.
+# - while a migration is in progress (see `matrix_authentication_service_migration_in_progress`),
+#   we don't even add compatibility layer labels, so MAS would not be used anyway.
+#
+# Still, it's probably safer to stop it anyway.
+- name: Ensure Matrix Authentication Service is stopped
+  ansible.builtin.service:
+    name: matrix-authentication-service
+    state: stopped
+  register: matrix_authentication_service_mas_ensure_stopped_result
+
+- name: Generate syn2mas migration command
+  ansible.builtin.set_fact:
+    matrix_authentication_service_syn2mas_migration_command: >-
+      {{ devture_systemd_docker_base_host_command_docker }} run
+      --rm
+      --name=matrix-authentication-service-syn2mas
+      --log-driver=none
+      --user={{ matrix_authentication_service_uid }}:{{ matrix_authentication_service_gid }}
+      --cap-drop=ALL
+      --network={{ matrix_authentication_service_syn2mas_container_network }}
+      --mount type=bind,src={{ matrix_authentication_service_syn2mas_synapse_homeserver_config_path }},dst=/homeserver.yaml,ro
+      --mount type=bind,src={{ matrix_authentication_service_config_path }}/config.yaml,dst=/mas-config.yaml,ro
+      {{ matrix_authentication_service_syn2mas_container_image }}
+      --command=migrate
+      --synapseConfigFile=/homeserver.yaml
+      --masConfigFile=/mas-config.yaml
+      {% if matrix_authentication_service_syn2mas_dry_run | bool %}--dryRun{% endif %}
+  tags:
+    - skip_ansible_lint
+
+# This is a hack.
+# See: https://ansibledaily.com/print-to-standard-output-without-escaping/
+#
+# We want to run `debug: msg=".."`, but that dumps it as JSON and escapes double quotes within it,
+# which ruins the command (`matrix_authentication_service_syn2mas_migration_command`)
+- name: Note about syn2mas migration
+  ansible.builtin.set_fact:
+    dummy: true
+  with_items:
+    - >-
+        Running syn2mas migration using the following command: `{{ matrix_authentication_service_syn2mas_migration_command }}`.
+        If this crashes, you can stop Synapse (`systemctl stop matrix-synapse`) and run the command manually.
+
+- name: Perform syn2mas migration
+  ansible.builtin.command:
+    cmd: "{{ matrix_authentication_service_syn2mas_migration_command }}"
+  register: matrix_authentication_service_syn2mas_migration_command_result
+  changed_when: matrix_authentication_service_syn2mas_migration_command_result.rc == 0
+
+- name: Print syn2mas migration command result
+  ansible.builtin.debug:
+    var: matrix_authentication_service_syn2mas_migration_command_result
+
+- name: Ensure Synapse is started (if it previously was)
+  when: "not matrix_authentication_service_syn2mas_dry_run and matrix_authentication_service_synapse_ensure_stopped_result.changed"
+  ansible.builtin.service:
+    name: matrix-synapse
+    state: started
+
+- name: Ensure Matrix Authentication Service is started (if it previously was)
+  when: "not matrix_authentication_service_syn2mas_dry_run and matrix_authentication_service_mas_ensure_stopped_result.changed"
+  ansible.builtin.service:
+    name: matrix-authentication-service
+    state: started

roles/custom/matrix-authentication-service/tasks/uninstall.yml

@@ -0,0 +1,25 @@
+---
+
+- name: Check existence of matrix-authentication-service service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-authentication-service.service"
+  register: matrix_authentication_service_service_stat
+
+- when: matrix_authentication_service_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-authentication-service is stopped
+      ansible.builtin.service:
+        name: matrix-authentication-service
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure matrix-authentication-service.service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-authentication-service.service"
+        state: absent
+
+    - name: Ensure Matrix Authentication Service paths don't exist
+      ansible.builtin.file:
+        path: "{{ matrix_authentication_service_base_path }}"
+        state: absent

roles/custom/matrix-authentication-service/tasks/util/prepare_key.yml

@@ -0,0 +1,12 @@
+---
+
+- name: Prepare Matrix Authentication Service private key file path ({{ private_key_definition.key_file }})
+  ansible.builtin.set_fact:
+    matrix_authentication_service_private_key_file_path: "{{ matrix_authentication_service_data_keys_path }}/{{ private_key_definition.key_file }}"
+
+- name: Prepare Matrix Authentication Service private key file ({{ private_key_definition.key_file }})
+  ansible.builtin.command:
+    cmd: "{{ private_key_definition.generation_command | replace('__KEY_FILE_PATH__', matrix_authentication_service_private_key_file_path) }}"
+    creates: "{{ matrix_authentication_service_private_key_file_path }}"
+  become: true
+  become_user: "{{ matrix_user_username }}"

roles/custom/matrix-authentication-service/tasks/validate_config.yml

@@ -0,0 +1,31 @@
+---
+
+- name: Fail if required matrix-authentication-service settings not defined
+  ansible.builtin.fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and vars[item.name] | length == 0"
+  with_items:
+    - {'name': 'matrix_authentication_service_hostname', when: true}
+    - {'name': 'matrix_authentication_service_config_database_username', when: true}
+    - {'name': 'matrix_authentication_service_config_database_password', when: true}
+    - {'name': 'matrix_authentication_service_config_database_host', when: true}
+    - {'name': 'matrix_authentication_service_config_database_database', when: true}
+    - {'name': 'matrix_authentication_service_config_secrets_encryption', when: true}
+    - {'name': 'matrix_authentication_service_config_matrix_homeserver', when: true}
+    - {'name': 'matrix_authentication_service_config_matrix_secret', when: true}
+    - {'name': 'matrix_authentication_service_config_matrix_endpoint', when: true}
+    - {'name': 'matrix_authentication_service_container_labels_public_main_hostname', when: "{{ matrix_authentication_service_container_labels_traefik_enabled }}"}
+    - {'name': 'matrix_authentication_service_container_labels_public_compatibility_layer_hostname', when: "{{ matrix_authentication_service_container_labels_public_compatibility_layer_enabled }}"}
+    - {'name': 'matrix_authentication_service_container_labels_internal_compatibility_layer_entrypoints', when: "{{ matrix_authentication_service_container_labels_internal_compatibility_layer_enabled }}"}
+    - {'name': 'matrix_authentication_service_config_email_hostname', when: "{{ matrix_authentication_service_config_email_transport == 'smtp' }}"}
+
+- name: Fail if matrix_authentication_service_config_secrets_encryption is not 64 characters long
+  ansible.builtin.fail:
+    msg: "matrix_authentication_service_config_secrets_encryption must be exactly 64 characters long (preferably generated via `openssl rand -hex 32`)"
+  when: "matrix_authentication_service_config_secrets_encryption | length != 64"
+
+- name: Fail if matrix_authentication_service_config_email_transport is invalid
+  ansible.builtin.fail:
+    msg: "matrix_authentication_service_config_email_transport must be one of: blackhole, smtp, or aws_ses"
+  when: "matrix_authentication_service_config_email_transport not in ['blackhole', 'smtp', 'aws_ses']"

roles/custom/matrix-authentication-service/templates/bin/mas-cli.j2

@@ -0,0 +1,16 @@
+#jinja2: lstrip_blocks: "True"
+#!/bin/bash
+
+args=$@
+
+if [ $# -eq 0 ]; then
+    args="help"
+fi
+
+if [ -t 0 ]; then
+    tty_option="-it"
+else
+    tty_option=""
+fi
+
+{{ devture_systemd_docker_base_host_command_docker }} exec $tty_option matrix-authentication-service mas-cli $args

roles/custom/matrix-authentication-service/templates/bin/register-user.j2

@@ -0,0 +1,17 @@
+#jinja2: lstrip_blocks: "True"
+#!/bin/bash
+
+if [ $# -ne 3 ]; then
+	echo "Usage: "$0" <username> <password> <admin access: 0 or 1>"
+	exit 1
+fi
+
+user=$1
+password=$2
+admin=$3
+
+if [ "$admin" -eq "1" ]; then
+	{{ devture_systemd_docker_base_host_command_docker }} exec matrix-authentication-service mas-cli manage register-user --yes -p "$password" --admin "$user"
+else
+	{{ devture_systemd_docker_base_host_command_docker }} exec matrix-authentication-service mas-cli manage register-user --yes -p "$password" --no-admin "$user"
+fi

roles/custom/matrix-authentication-service/templates/config.yaml.j2

@@ -0,0 +1,82 @@
+#jinja2: lstrip_blocks: "True"
+http:
+  listeners:
+  - name: web
+    resources:
+    - name: discovery
+    - name: human
+    - name: oauth
+    - name: compat
+    - name: graphql
+    - name: assets
+    binds:
+    - address: '[::]:8080'
+    proxy_protocol: false
+    prefix: {{ matrix_authentication_service_path_prefix }}
+  - name: internal
+    resources:
+    - name: health
+    binds:
+    - host: localhost
+      port: 8081
+    proxy_protocol: false
+    prefix: {{ matrix_authentication_service_path_prefix }}
+  trusted_proxies: {{ matrix_authentication_service_config_http_trusted_proxies | to_json }}
+  public_base: {{ matrix_authentication_service_config_http_public_base | to_json }}
+  issuer: {{ matrix_authentication_service_config_http_issuer | to_json }}
+
+database:
+  host: {{ matrix_authentication_service_config_database_host | to_json }}
+  port: {{ matrix_authentication_service_config_database_port | to_json }}
+  username: {{ matrix_authentication_service_config_database_username | to_json }}
+  password: {{ matrix_authentication_service_config_database_password | to_json }}
+  database: {{ matrix_authentication_service_config_database_database | to_json }}
+  ssl_mode: {{ matrix_authentication_service_config_database_ssl_mode | to_json }}
+  max_connections: {{ matrix_authentication_service_config_database_max_connections | to_json }}
+  min_connections: {{ matrix_authentication_service_config_database_min_connections | to_json }}
+  connect_timeout: {{ matrix_authentication_service_config_database_connect_timeout | to_json }}
+  idle_timeout: {{ matrix_authentication_service_config_database_idle_timeout | to_json }}
+  max_lifetime: {{ matrix_authentication_service_config_database_max_lifetime | to_json }}
+
+email:
+  from: {{ matrix_authentication_service_config_email_from | to_json }}
+  reply_to: {{ matrix_authentication_service_config_email_reply_to | to_json }}
+  transport: {{ matrix_authentication_service_config_email_transport | to_json }}
+  {% if matrix_authentication_service_config_email_transport == 'smtp' %}
+  mode: {{ matrix_authentication_service_config_email_mode | to_json }}
+  hostname: {{ matrix_authentication_service_config_email_hostname | to_json }}
+  port: {{ matrix_authentication_service_config_email_port | int | to_json }}
+  {% if matrix_authentication_service_config_email_username %}
+  username: {{ matrix_authentication_service_config_email_username | to_json }}
+  {% endif %}
+  {% if matrix_authentication_service_config_email_password %}
+  password: {{ matrix_authentication_service_config_email_password | to_json }}
+  {% endif %}
+  {% endif %}
+secrets:
+  encryption: {{ matrix_authentication_service_config_secrets_encryption | to_json }}
+  keys: {{ matrix_authentication_service_config_secrets_keys | to_json }}
+
+passwords:
+  enabled: {{ matrix_authentication_service_config_passwords_enabled | to_json }}
+  schemes: {{ matrix_authentication_service_config_passwords_schemes | to_json }}
+  minimum_complexity: {{ matrix_authentication_service_config_passwords_minimum_complexity | to_json }}
+
+matrix:
+  homeserver: {{ matrix_authentication_service_config_matrix_homeserver | to_json }}
+  secret: {{ matrix_authentication_service_config_matrix_secret | to_json }}
+  endpoint: {{ matrix_authentication_service_config_matrix_endpoint | to_json }}
+
+account:
+  email_change_allowed: {{ matrix_authentication_service_config_account_email_change_allowed | to_json }}
+  displayname_change_allowed: {{ matrix_authentication_service_config_account_displayname_change_allowed | to_json }}
+  password_registration_enabled: {{ matrix_authentication_service_config_account_password_registration_enabled | to_json }}
+  password_change_allowed: {{ matrix_authentication_service_config_account_password_change_allowed | to_json }}
+  password_recovery_enabled: {{ matrix_authentication_service_config_account_password_recovery_enabled | to_json }}
+
+clients: {{ matrix_authentication_service_config_clients | to_json }}
+
+{% if matrix_authentication_service_config_upstream_oauth2_providers | length > 0 %}
+upstream_oauth2:
+  providers: {{ matrix_authentication_service_config_upstream_oauth2_providers | to_json }}
+{% endif %}

roles/custom/matrix-authentication-service/templates/env.j2

@@ -0,0 +1 @@
+{{ matrix_authentication_service_environment_variables_extension }}

roles/custom/matrix-authentication-service/templates/labels.j2

@@ -0,0 +1,134 @@
+{% if matrix_authentication_service_container_labels_traefik_enabled %}
+traefik.enable=true
+
+{% if matrix_authentication_service_container_labels_traefik_docker_network %}
+traefik.docker.network={{ matrix_authentication_service_container_labels_traefik_docker_network }}
+{% endif %}
+
+traefik.http.services.matrix-authentication-service.loadbalancer.server.port=8080
+
+########################################################################################
+#                                                                                      #
+# Public Main                                                                          #
+#                                                                                      #
+########################################################################################
+
+{% set main_middlewares = [] %}
+
+{% if matrix_authentication_service_container_labels_public_main_path_prefix != '/' %}
+traefik.http.middlewares.matrix-authentication-service-slashless-redirect.redirectregex.regex=({{ matrix_authentication_service_container_labels_public_main_path_prefix | quote }})$
+traefik.http.middlewares.matrix-authentication-service-slashless-redirect.redirectregex.replacement=${1}/
+{% set main_middlewares = main_middlewares + ['matrix-authentication-service-slashless-redirect'] %}
+{% endif %}
+
+{% if matrix_authentication_service_container_labels_traefik_additional_response_headers.keys() | length > 0 %}
+{% for name, value in matrix_authentication_service_container_labels_traefik_additional_response_headers.items() %}
+traefik.http.middlewares.matrix-authentication-service-add-headers.headers.customresponseheaders.{{ name }}={{ value }}
+{% endfor %}
+{% set main_middlewares = main_middlewares + ['matrix-authentication-service-add-headers'] %}
+{% endif %}
+
+traefik.http.routers.matrix-authentication-service.rule={{ matrix_authentication_service_container_labels_public_main_rule }}
+
+{% if matrix_authentication_service_container_labels_public_main_priority | int > 0 %}
+traefik.http.routers.matrix-authentication-service.priority={{ matrix_authentication_service_container_labels_public_main_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-authentication-service.service=matrix-authentication-service
+
+{% if main_middlewares | length > 0 %}
+traefik.http.routers.matrix-authentication-service.middlewares={{ main_middlewares | join(',') }}
+{% endif %}
+
+traefik.http.routers.matrix-authentication-service.entrypoints={{ matrix_authentication_service_container_labels_public_main_entrypoints }}
+traefik.http.routers.matrix-authentication-service.tls={{ matrix_authentication_service_container_labels_public_main_tls | to_json }}
+{% if matrix_authentication_service_container_labels_public_main_tls %}
+traefik.http.routers.matrix-authentication-service.tls.certResolver={{ matrix_authentication_service_container_labels_public_main_tls_certResolver }}
+{% endif %}
+
+########################################################################################
+#                                                                                      #
+# /Public Main                                                                         #
+#                                                                                      #
+########################################################################################
+
+{% if matrix_authentication_service_container_labels_public_compatibility_layer_enabled %}
+########################################################################################
+#                                                                                      #
+# Public Compatibility Layer                                                           #
+#                                                                                      #
+########################################################################################
+
+{% set compatibility_layer_middlewares = [] %}
+
+{% if matrix_authentication_service_container_labels_public_main_path_prefix != '/' %}
+traefik.http.middlewares.matrix-authentication-service-add-prefix.addprefix.prefix={{ matrix_authentication_service_container_labels_public_main_path_prefix }}
+{% set compatibility_layer_middlewares = compatibility_layer_middlewares + ['matrix-authentication-service-add-prefix'] %}
+{% endif %}
+
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.rule={{ matrix_authentication_service_container_labels_public_compatibility_layer_rule }}
+
+{% if matrix_authentication_service_container_labels_public_compatibility_layer_priority | int > 0 %}
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.priority={{ matrix_authentication_service_container_labels_public_compatibility_layer_priority }}
+{% endif %}
+
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.service=matrix-authentication-service
+
+{% if compatibility_layer_middlewares | length > 0 %}
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.middlewares={{ compatibility_layer_middlewares | join(',') }}
+{% endif %}
+
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.entrypoints={{ matrix_authentication_service_container_labels_public_compatibility_layer_entrypoints }}
+
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.tls={{ matrix_authentication_service_container_labels_public_compatibility_layer_tls | to_json }}
+{% if matrix_authentication_service_container_labels_public_compatibility_layer_tls %}
+traefik.http.routers._internalmatrix-authentication-service-public-compatibility-layer.tls.certResolver={{ matrix_authentication_service_container_labels_public_compatibility_layer_tls_certResolver }}
+{% endif %}
+
+########################################################################################
+#                                                                                      #
+# /Public Compatibility Layer                                                          #
+#                                                                                      #
+########################################################################################
+{% endif %}
+
+
+{% if matrix_authentication_service_container_labels_internal_compatibility_layer_enabled %}
+########################################################################################
+#                                                                                      #
+# Internal Compatibility Layer                                                         #
+#                                                                                      #
+########################################################################################
+
+{% set compatibility_layer_middlewares = [] %}
+
+{% if matrix_authentication_service_container_labels_public_main_path_prefix != '/' %}
+traefik.http.middlewares.matrix-authentication-service-add-prefix.addprefix.prefix={{ matrix_authentication_service_container_labels_public_main_path_prefix }}
+{% set compatibility_layer_middlewares = compatibility_layer_middlewares + ['matrix-authentication-service-add-prefix'] %}
+{% endif %}
+
+traefik.http.routers._internalmatrix-authentication-service-internal-compatibility-layer.rule={{ matrix_authentication_service_container_labels_internal_compatibility_layer_rule }}
+
+{% if matrix_authentication_service_container_labels_internal_compatibility_layer_priority | int > 0 %}
+traefik.http.routers._internalmatrix-authentication-service-internal-compatibility-layer.priority={{ matrix_authentication_service_container_labels_internal_compatibility_layer_priority }}
+{% endif %}
+
+traefik.http.routers._internalmatrix-authentication-service-internal-compatibility-layer.service=matrix-authentication-service
+
+{% if compatibility_layer_middlewares | length > 0 %}
+traefik.http.routers._internalmatrix-authentication-service-internal-compatibility-layer.middlewares={{ compatibility_layer_middlewares | join(',') }}
+{% endif %}
+
+traefik.http.routers._internalmatrix-authentication-service-internal-compatibility-layer.entrypoints={{ matrix_authentication_service_container_labels_internal_compatibility_layer_entrypoints }}
+
+########################################################################################
+#                                                                                      #
+# /Internal Compatibility Layer                                                        #
+#                                                                                      #
+########################################################################################
+{% endif %}
+
+
+{% endif %}
+
+{{ matrix_authentication_service_container_labels_additional_labels }}

roles/custom/matrix-authentication-service/templates/provider/anthropic-config.yml.j2

@@ -0,0 +1,13 @@
+#jinja2: lstrip_blocks: "True"
+base_url: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_base_url | to_json }}
+
+api_key: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_api_key | to_json }}
+
+{% if matrix_authentication_service_config_agents_static_definitions_anthropic_config_text_generation_enabled %}
+text_generation:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_text_generation_model_id | to_json }}
+  prompt: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_text_generation_prompt | to_json }}
+  temperature: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_text_generation_temperature | to_json }}
+  max_response_tokens: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_text_generation_max_response_tokens | int | to_json }}
+  max_context_tokens: {{ matrix_authentication_service_config_agents_static_definitions_anthropic_config_text_generation_max_context_tokens | int | to_json }}
+{% endif %}

roles/custom/matrix-authentication-service/templates/provider/groq-config.yml.j2

@@ -0,0 +1,18 @@
+#jinja2: lstrip_blocks: "True"
+base_url: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_base_url | to_json }}
+
+api_key: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_api_key | to_json }}
+
+{% if matrix_authentication_service_config_agents_static_definitions_groq_config_text_generation_enabled %}
+text_generation:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_text_generation_model_id | to_json }}
+  prompt: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_text_generation_prompt | to_json }}
+  temperature: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_text_generation_temperature | to_json }}
+  max_response_tokens: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_text_generation_max_response_tokens | int | to_json }}
+  max_context_tokens: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_text_generation_max_context_tokens | int | to_json }}
+{% endif %}
+
+{% if matrix_authentication_service_config_agents_static_definitions_groq_config_speech_to_text_enabled %}
+speech_to_text:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_groq_config_speech_to_text_model_id | to_json }}
+{% endif %}

roles/custom/matrix-authentication-service/templates/provider/mistral-config.yml.j2

@@ -0,0 +1,13 @@
+#jinja2: lstrip_blocks: "True"
+base_url: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_base_url | to_json }}
+
+api_key: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_api_key | to_json }}
+
+{% if matrix_authentication_service_config_agents_static_definitions_mistral_config_text_generation_enabled %}
+text_generation:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_text_generation_model_id | to_json }}
+  prompt: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_text_generation_prompt | to_json }}
+  temperature: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_text_generation_temperature | to_json }}
+  max_response_tokens: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_text_generation_max_response_tokens | int | to_json }}
+  max_context_tokens: {{ matrix_authentication_service_config_agents_static_definitions_mistral_config_text_generation_max_context_tokens | int | to_json }}
+{% endif %}

roles/custom/matrix-authentication-service/templates/provider/openai-config.yml.j2

@@ -0,0 +1,33 @@
+#jinja2: lstrip_blocks: "True"
+base_url: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_base_url | to_json }}
+
+api_key: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_api_key | to_json }}
+
+{% if matrix_authentication_service_config_agents_static_definitions_openai_config_text_generation_enabled %}
+text_generation:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_generation_model_id | to_json }}
+  prompt: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_generation_prompt | to_json }}
+  temperature: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_generation_temperature | to_json }}
+  max_response_tokens: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_generation_max_response_tokens | int | to_json }}
+  max_context_tokens: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_generation_max_context_tokens | int | to_json }}
+{% endif %}
+
+{% if matrix_authentication_service_config_agents_static_definitions_openai_config_speech_to_text_enabled %}
+speech_to_text:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_speech_to_text_model_id | to_json }}
+{% endif %}
+
+{% if matrix_authentication_service_config_agents_static_definitions_openai_config_text_to_speech_enabled %}
+text_to_speech:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_to_speech_model_id | to_json }}
+  voice: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_to_speech_voice | to_json }}
+  speed: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_to_speech_speed | float }}
+  response_format: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_text_to_speech_response_format | to_json }}
+{% endif %}
+
+{% if matrix_authentication_service_config_agents_static_definitions_openai_config_image_generation_enabled %}
+image_generation:
+  model_id: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_image_generation_model_id | to_json }}
+  style: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_image_generation_style | to_json }}
+  size: {{ matrix_authentication_service_config_agents_static_definitions_openai_config_image_generation_size | to_json }}
+{% endif %}

roles/custom/matrix-authentication-service/templates/systemd/matrix-authentication-service.service.j2

@@ -0,0 +1,49 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=Matrix Authentication Service
+{% for service in matrix_authentication_service_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_authentication_service_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-authentication-service 2>/dev/null || true'
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-authentication-service 2>/dev/null || true'
+
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
+			--rm \
+			--name=matrix-authentication-service \
+			--log-driver=none \
+			--user={{ matrix_authentication_service_uid }}:{{ matrix_authentication_service_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--network={{ matrix_authentication_service_container_network }} \
+			--env-file={{ matrix_authentication_service_config_path }}/env \
+			--label-file={{ matrix_authentication_service_config_path }}/labels \
+			--mount type=bind,src={{ matrix_authentication_service_config_path }}/config.yaml,dst=/config.yaml,ro \
+			--mount type=bind,src={{ matrix_authentication_service_data_keys_path }},dst=/keys,ro \
+			{% for arg in matrix_authentication_service_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_authentication_service_container_image }}
+
+{% for network in matrix_authentication_service_container_additional_networks %}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-authentication-service
+{% endfor %}
+
+ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-authentication-service
+
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-authentication-service 2>/dev/null || true'
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-authentication-service 2>/dev/null || true'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-authentication-service
+
+[Install]
+WantedBy=multi-user.target

roles/custom/matrix-authentication-service/vars/main.yml

@@ -0,0 +1,6 @@
+---
+
+# Like `matrix_authentication_service_config_http_public_base` but a private base URL only accessible from within the container network.
+matrix_authentication_service_http_base_container_url: "http://matrix-authentication-service:8080{{ '/' if matrix_authentication_service_path_prefix == '/' else (matrix_authentication_service_path_prefix + '/') }}"
+
+matrix_authentication_service_account_management_url: "{{ matrix_authentication_service_config_http_public_base }}account"

roles/custom/matrix-static-files/defaults/main.yml

@@ -145,6 +145,13 @@ matrix_static_files_file_matrix_client_property_m_integrations_managers_ui_url:
 # See: https://github.com/element-hq/element-web/blob/develop/docs/jitsi.md#configuring-element-to-use-your-self-hosted-jitsi-server
 matrix_static_files_file_matrix_client_property_io_element_jitsi_preferred_domain: ""
 
+# Controls if the org.matrix.msc3575.authentication section of the /.well-known/matrix/client file is enabled.
+matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_enabled: false
+# Controls the org.matrix.msc2965.authentication/issuer property in the /.well-known/matrix/client file
+matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_issuer: ""
+# Controls the org.matrix.msc2965.authentication/account property in the /.well-known/matrix/client file
+matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_account: ""
+
 # Controls the org.matrix.msc3575.proxy/url (sliding sync) property in the /.well-known/matrix/client file
 matrix_static_files_file_matrix_client_property_org_matrix_msc3575_proxy_url: ""
 

roles/custom/matrix-static-files/tasks/validate_config.yml

@@ -4,7 +4,7 @@
   ansible.builtin.fail:
     msg: >-
       You need to define a required configuration setting (`{{ item.name }}`).
-  when: "item.when | bool and vars[item.name] == ''"
+  when: "item.when | bool and vars[item.name] | length == 0"
   with_items:
     - {'name': 'matrix_static_files_container_labels_well_known_matrix_endpoint_traefik_hostname', when: "{{ matrix_static_files_container_labels_well_known_matrix_endpoint_enabled }}"}
     - {'name': 'matrix_static_files_container_labels_well_known_matrix_endpoint_traefik_path_prefix', when: "{{ matrix_static_files_container_labels_well_known_matrix_endpoint_enabled }}"}
@@ -13,3 +13,6 @@
     - {'name': 'matrix_static_files_container_labels_base_domain_traefik_path_prefix', when: "{{ matrix_static_files_container_labels_base_domain_enabled }}"}
 
     - {'name': 'matrix_static_files_container_labels_base_domain_root_path_redirection_url', when: "{{ matrix_static_files_container_labels_base_domain_enabled and matrix_static_files_container_labels_base_domain_root_path_redirection_enabled }}"}
+
+    - {'name': 'matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_issuer', when: "{{ matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_enabled and matrix_static_files_container_labels_base_domain_root_path_redirection_enabled }}"}
+    - {'name': 'matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_account', when: "{{ matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_enabled and matrix_static_files_container_labels_base_domain_root_path_redirection_enabled }}"}

roles/custom/matrix-static-files/templates/public/.well-known/matrix/client.j2

@@ -30,6 +30,12 @@
 		"url": "{{ matrix_static_files_file_matrix_client_property_org_matrix_msc3575_proxy_url }}"
 	}
 	{% endif %}
+	{% if matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_enabled %},
+	"org.matrix.msc2965.authentication": {
+		"issuer": {{ matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_issuer | to_json }},
+		"account": {{ matrix_static_files_file_matrix_client_property_org_matrix_msc2965_authentication_account | to_json }}
+	}
+	{% endif %}
 	{% if matrix_static_files_file_matrix_client_property_m_tile_server_entries_enabled %},
 	"m.tile_server": {
         "map_style_url": "{{ matrix_static_files_file_matrix_client_property_m_tile_server_map_style_url }}"

roles/custom/matrix-synapse/defaults/main.yml

@@ -1129,6 +1129,61 @@ matrix_synapse_email_client_base_url: "{{ 'https' if matrix_playbook_ssl_enabled
 matrix_synapse_email_invite_client_location: "https://app.element.io"
 
 
+################################################################################
+#
+# Next-generation auth for Matrix, based on OAuth 2.0/OIDC
+#
+################################################################################
+
+# Controls whether to enable the "Next-generation auth for Matrix, based on OAuth 2.0/OIDC" experimental feature.
+#
+# See:
+# - https://matrix.org/blog/2023/09/better-auth/
+# - https://github.com/matrix-org/matrix-spec-proposals/pull/3861
+matrix_synapse_experimental_features_msc3861_enabled: false
+
+# Specifies the issuer URL for the OAuth 2.0/OIDC authentication provider.
+#
+# This can be set to a private (container) URL.
+#
+# Example: https://matrix.example.com/auth/
+matrix_synapse_experimental_features_msc3861_issuer: ''
+
+# Specifies the introspection endpoint URL for the OAuth 2.0/OIDC authentication provider.
+#
+# This can be set to a private (container) URL.
+#
+# If this is left empty, `{issuer}/.well-known/openid-configuration` will be fetched and the `introspection_endpoint` will be extracted from there.
+# We define it explicitly, because this allows us to override it and use an internal (container network) URL instead of using the public one.
+# Avoiding public addresses is an optimization that decreases overhead due to public networking and SSL termination.
+#
+# Example: https://matrix.example.com/auth/oauth2/introspect
+matrix_synapse_experimental_features_msc3861_introspection_endpoint: "{{ matrix_synapse_experimental_features_msc3861_issuer + 'oauth2/introspect' }}"
+
+# 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.
+matrix_synapse_experimental_features_msc3861_client_id: '0000000000000000000SYNAPSE'
+
+matrix_synapse_experimental_features_msc3861_client_auth_method: client_secret_basic
+
+matrix_synapse_experimental_features_msc3861_client_secret: ''
+
+# A token that can be used to make admin API calls.
+# Matches `matrix.secret` in the matrix-authentication-service config
+matrix_synapse_experimental_features_msc3861_admin_token: ''
+
+# URL to advertise to clients where users can self-manage their account.
+matrix_synapse_experimental_features_msc3861_account_management_url: ''
+
+################################################################################
+#
+# /Next-generation auth for Matrix, based on OAuth 2.0/OIDC
+#
+################################################################################
+
+
 # Enable this to activate the REST auth password provider module.
 # See: https://github.com/ma1uta/matrix-synapse-rest-password-provider
 matrix_synapse_ext_password_provider_rest_auth_enabled: false
@@ -1406,3 +1461,8 @@ matrix_synapse_configuration_extension: "{{ matrix_synapse_configuration_extensi
 # Holds the final Synapse configuration (a combination of the default and its extension).
 # You most likely don't need to touch this variable. Instead, see `matrix_synapse_configuration_yaml`.
 matrix_synapse_configuration: "{{ matrix_synapse_configuration_yaml | from_yaml | combine(matrix_synapse_configuration_extension, recursive=True) }}"
+
+# Holds the path to the register-user script provided by the Matrix Authentication Service.
+# When the Matrix Authentication Service is enabled, the register-user script from this role cannot be used
+# and users will be pointed to the one provided by Matrix Authentication Service.
+matrix_synapse_register_user_script_matrix_authentication_service_path: ""

roles/custom/matrix-synapse/tasks/main.yml

@@ -54,7 +54,7 @@
 - tags:
     - register-user
   block:
-    - when: matrix_synapse_enabled | bool
+    - when: matrix_synapse_enabled and not matrix_synapse_experimental_features_msc3861_enabled
       ansible.builtin.include_tasks: "{{ role_path }}/tasks/register_user.yml"
 
 - tags:

roles/custom/matrix-synapse/tasks/validate_config.yml

@@ -4,7 +4,7 @@
   ansible.builtin.fail:
     msg: >-
       You need to define a required configuration setting (`{{ item.name }}`).
-  when: "item.when | bool and vars[item.name] == ''"
+  when: "item.when | bool and vars[item.name] | length == 0"
   with_items:
     - {'name': 'matrix_synapse_username', when: true}
     - {'name': 'matrix_synapse_uid', when: true}
@@ -32,6 +32,13 @@
     - {'name': 'matrix_synapse_metrics_proxying_hostname', when: "{{ matrix_synapse_metrics_proxying_enabled }}"}
     - {'name': 'matrix_synapse_metrics_proxying_path_prefix', when: "{{ matrix_synapse_metrics_proxying_enabled }}"}
 
+    - {'name': 'matrix_synapse_experimental_features_msc3861_issuer', when: "{{ matrix_synapse_experimental_features_msc3861_enabled }}"}
+    - {'name': 'matrix_synapse_experimental_features_msc3861_client_id', when: "{{ matrix_synapse_experimental_features_msc3861_enabled }}"}
+    - {'name': 'matrix_synapse_experimental_features_msc3861_client_auth_method', when: "{{ matrix_synapse_experimental_features_msc3861_enabled }}"}
+    - {'name': 'matrix_synapse_experimental_features_msc3861_client_secret', when: "{{ matrix_synapse_experimental_features_msc3861_enabled }}"}
+    - {'name': 'matrix_synapse_experimental_features_msc3861_admin_token', when: "{{ matrix_synapse_experimental_features_msc3861_enabled }}"}
+    - {'name': 'matrix_synapse_experimental_features_msc3861_account_management_url', when: "{{ matrix_synapse_experimental_features_msc3861_enabled }}"}
+
 - name: Fail if asking for more than 1 instance of single-instance workers
   ansible.builtin.fail:
     msg: >-
@@ -133,3 +140,17 @@
   when:
     - matrix_synapse_auto_accept_invites_enabled
     - matrix_synapse_ext_synapse_auto_accept_invite_enabled
+
+- name: Fail if known Synapse password provider modules are enabled when auth is delegated to Matrix Authentication Service
+  ansible.builtin.fail:
+    msg: "When Synapse is delegating authentication to Matrix Authentication Service, it does not make sense to enable password provider modules, because it is not Synapse that is handling authentication. Please disable {{ item }} before enabling Matrix Authentication Service integration for Synapse. Synapse will refuse to start otherwise."
+  when: matrix_synapse_experimental_features_msc3861_enabled and vars[item] | bool
+  with_items:
+    - matrix_synapse_ext_password_provider_rest_auth_enabled
+    - matrix_synapse_ext_password_provider_shared_secret_auth_enabled
+    - matrix_synapse_ext_password_provider_ldap_enabled
+
+- name: Fail if password config is enabled for Synapse when auth is delegated to Matrix Authentication Service
+  ansible.builtin.fail:
+    msg: "When Synapse is delegating authentication to Matrix Authentication Service, it doesn't make sense to enable the password config (`matrix_synapse_password_config_enabled: true`), because it is not Synapse that is handling authentication. Please remove your `matrix_synapse_password_config_enabled: true` setting before enabling Matrix Authentication Service integration for Synapse. Synapse will refuse to start otherwise."
+  when: matrix_synapse_experimental_features_msc3861_enabled and matrix_synapse_password_config_enabled

roles/custom/matrix-synapse/templates/synapse/bin/register-user.j2

@@ -1,6 +1,11 @@
 #jinja2: lstrip_blocks: "True"
 #!/bin/bash
 
+{% if matrix_synapse_experimental_features_msc3861_enabled %}
+	echo "Registering users is handled by the Matrix Authentication Service, so you cannot use this script anymore."
+	echo "Consider using the {{ matrix_synapse_register_user_script_matrix_authentication_service_path }} script instead."
+	exit 2
+{% else %}
 if [ $# -ne 3 ]; then
 	echo "Usage: "$0" <username> <password> <admin access: 0 or 1>"
 	exit 1
@@ -15,3 +20,4 @@ if [ "$admin" -eq "1" ]; then
 else
 	{{ devture_systemd_docker_base_host_command_docker }} exec matrix-synapse register_new_matrix_user -u "$user" -p "$password" -c /data/homeserver.yaml --no-admin http://localhost:{{ matrix_synapse_container_client_api_port }}
 fi
+{% endif %}

roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2

@@ -2974,5 +2974,17 @@ background_updates:
     #
     #default_batch_size: 50
 
+experimental_features:
+  {% if matrix_synapse_experimental_features_msc3861_enabled %}
+  msc3861:
+    enabled: true
+    issuer: {{ matrix_synapse_experimental_features_msc3861_issuer | to_json }}
+    introspection_endpoint: {{ matrix_synapse_experimental_features_msc3861_introspection_endpoint | to_json }}
+    client_id: {{ matrix_synapse_experimental_features_msc3861_client_id | to_json }}
+    client_auth_method: {{ matrix_synapse_experimental_features_msc3861_client_auth_method | to_json }}
+    client_secret: {{ matrix_synapse_experimental_features_msc3861_client_secret | to_json }}
+    admin_token: {{ matrix_synapse_experimental_features_msc3861_admin_token | to_json }}
+    account_management_url: {{ matrix_synapse_experimental_features_msc3861_account_management_url | to_json }}
+  {% endif %}
 
 # vim:ft=yaml

roles/custom/matrix-user-creator/tasks/setup.yml

@@ -8,22 +8,48 @@
   # Suppress logging to avoid dumping the credentials to the shell
   no_log: true
 
-- name: Ensure homeserver is started before creating Matrix users
+- when: not matrix_authentication_service_enabled | bool
+  block:
+    - name: Ensure homeserver is started before creating Matrix users
       ansible.builtin.service:
         name: "matrix-{{ matrix_homeserver_implementation }}.service"
         state: started
         daemon_reload: true
       register: matrix_user_registrator_homeserver_start_result
 
-- name: Wait a while, so that the homeserver can manage to start before creating Matrix users
+    - name: Wait a while, so that the homeserver can manage to start before creating Matrix users
       ansible.builtin.pause:
         seconds: "{{ matrix_user_creator_homeserver_start_wait_time_seconds }}"
       when: matrix_user_registrator_homeserver_start_result.changed | bool
 
-- name: Ensure Matrix users are created
+    - name: Ensure Matrix users are created for homeservers
+      when: not matrix_authentication_service_enabled | bool
       ansible.builtin.include_tasks: "{{ role_path }}/tasks/util/ensure_user_registered_{{ matrix_homeserver_implementation }}.yml"
       with_items: "{{ matrix_user_creator_users }}"
       loop_control:
         loop_var: user
       # Suppress logging to avoid dumping the credentials to the shell
       no_log: true
+
+- when: matrix_authentication_service_enabled | bool
+  block:
+    - name: Ensure Matrix Authentication Service is started before creating Matrix users
+      ansible.builtin.service:
+        name: "matrix-authentication-service.service"
+        state: started
+        daemon_reload: true
+      register: matrix_user_registrator_mas_start_result
+
+    - name: Wait a while, so that the Matrix Authentication Service can manage to start before creating Matrix users
+      ansible.builtin.pause:
+        seconds: "{{ matrix_user_creator_homeserver_start_wait_time_seconds }}"
+      when: matrix_user_registrator_mas_start_result.changed | bool
+
+    - name: Ensure Matrix users are created for Matrix Authentication Service
+      when: matrix_authentication_service_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/util/ensure_user_registered_matrix_authentication_service.yml"
+      with_items: "{{ matrix_user_creator_users }}"
+      loop_control:
+        loop_var: user
+      # Suppress logging to avoid dumping the credentials to the shell
+      no_log: true

roles/custom/matrix-user-creator/tasks/util/ensure_user_registered_matrix_authentication_service.yml

@@ -0,0 +1,19 @@
+---
+
+- name: Ensure Matrix Authentication Service user registered - {{ user.username | quote }}
+  ansible.builtin.command:
+    cmd: |-
+      {{ devture_systemd_docker_base_host_command_docker }} exec matrix-authentication-service
+      mas-cli manage register-user
+      -p {{ user.initial_password | quote }}
+      --yes
+      --ignore-password-complexity
+      {% if user.initial_type == 'admin' %}
+        --admin
+      {% else %}
+        --no-admin
+      {% endif %}
+      {{ user.username | quote }}
+  register: matrix_authentication_service_register_user_result
+  changed_when: "matrix_authentication_service_register_user_result.rc == 0 and 'Error: User already exists' not in matrix_authentication_service_register_user_result.stderr"
+  failed_when: "matrix_authentication_service_register_user_result.rc != 0 and 'Error: User already exists' not in matrix_authentication_service_register_user_result.stderr"

setup.yml

@@ -49,6 +49,7 @@
 
     - galaxy/redis
     - galaxy/keydb
+    - role: custom/matrix-authentication-service
     - custom/matrix-corporal
     - custom/matrix-appservice-draupnir-for-all
     - custom/matrix-appservice-double-puppet