Add support for Matrix Authentication Service

Fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3108

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3562

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