From de1ba73f40166877aac7c0588be80741b63f557f Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Wed, 15 Jul 2026 07:29:35 +0300 Subject: [PATCH] Add dedicated CAPTCHA variables to matrix-authentication-service Matrix Authentication Service supports CAPTCHA protection (ReCaptcha v2, Cloudflare Turnstile, hCaptcha) for certain operations like self-service password registration, but configuring it required going through matrix_authentication_service_configuration_extension_yaml. Expose it via dedicated variables (matrix_authentication_service_config_captcha_service, _site_key and _secret_key), validate the service value and key presence, and document the setup in the captcha documentation page, which so far only covered Synapse and Dendrite. Related to #5344 Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 6 +++++ docs/configuring-captcha.md | 15 +++++++++++ .../defaults/main.yml | 27 +++++++++++++++++++ .../tasks/validate_config.yml | 7 +++++ .../templates/config.yaml.j2 | 7 +++++ 5 files changed, 62 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e8daebfe4..ad55ead1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +# 2026-07-15 + +## Dedicated CAPTCHA variables for Matrix Authentication Service + +[Matrix Authentication Service](./docs/configuring-playbook-matrix-authentication-service.md) can now be protected with CAPTCHA (ReCaptcha v2, Cloudflare Turnstile, or hCaptcha) via dedicated variables, instead of going through `matrix_authentication_service_configuration_extension_yaml`. See the [captcha documentation](./docs/configuring-captcha.md#matrix-authentication-service) for details. + # 2026-07-14 ## The playbook no longer ships a custom welcome page for Element Web diff --git a/docs/configuring-captcha.md b/docs/configuring-captcha.md index a5ad1085d..5b20a6d90 100644 --- a/docs/configuring-captcha.md +++ b/docs/configuring-captcha.md @@ -15,6 +15,8 @@ Captcha can be enabled for this home server. This file explains how to do that. The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead. +If you are using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), captcha is configured there instead (it handles registration), and [Cloudflare Turnstile](https://www.cloudflare.com/application-services/products/turnstile/) is supported as well. See [Matrix Authentication Service](#matrix-authentication-service) below. + ## ReCaptcha ### Getting keys @@ -61,3 +63,16 @@ matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api. matrix_dendrite_client_api_recaptcha_form_field: 'h-captcha-response' matrix_dendrite_client_api_recaptcha_sitekey_class: 'h-captcha' ``` + +## Matrix Authentication Service + +When [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) is enabled, registration and other account operations are handled by it, so captcha protection is configured there (the Synapse and Dendrite settings above do not apply). + +Matrix Authentication Service supports [ReCaptcha v2](http://www.google.com/recaptcha/admin), [Cloudflare Turnstile](https://www.cloudflare.com/application-services/products/turnstile/) and [hCaptcha](https://dashboard.hcaptcha.com/sites/new). Obtain a site/secret key pair from your chosen service, then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: + +```yaml +# Valid values: recaptcha_v2, cloudflare_turnstile, hcaptcha +matrix_authentication_service_config_captcha_service: recaptcha_v2 +matrix_authentication_service_config_captcha_site_key: 'YOUR_SITE_KEY' +matrix_authentication_service_config_captcha_secret_key: 'YOUR_SECRET_KEY' +``` diff --git a/roles/custom/matrix-authentication-service/defaults/main.yml b/roles/custom/matrix-authentication-service/defaults/main.yml index 4fe1ca7ed..b095f8e92 100644 --- a/roles/custom/matrix-authentication-service/defaults/main.yml +++ b/roles/custom/matrix-authentication-service/defaults/main.yml @@ -260,6 +260,33 @@ matrix_authentication_service_config_account_registration_token_required: false ######################################################################################## +######################################################################################## +# # +# Captcha configuration # +# # +######################################################################################## + +# Controls the `captcha.service` configuration setting. +# +# Which service to use for CAPTCHA protection of certain operations (like self-service password registration). +# Valid values: recaptcha_v2, cloudflare_turnstile, hcaptcha +# When defined, `matrix_authentication_service_config_captcha_site_key` and `matrix_authentication_service_config_captcha_secret_key` must be defined as well. +# Leave empty to disable CAPTCHA protection. +matrix_authentication_service_config_captcha_service: "" + +# Controls the `captcha.site_key` configuration setting. +matrix_authentication_service_config_captcha_site_key: "" + +# Controls the `captcha.secret_key` configuration setting. +matrix_authentication_service_config_captcha_secret_key: "" + +######################################################################################## +# # +# /Captcha configuration # +# # +######################################################################################## + + ######################################################################################## # # # Database configuration # diff --git a/roles/custom/matrix-authentication-service/tasks/validate_config.yml b/roles/custom/matrix-authentication-service/tasks/validate_config.yml index 95b33499f..becbbbf48 100644 --- a/roles/custom/matrix-authentication-service/tasks/validate_config.yml +++ b/roles/custom/matrix-authentication-service/tasks/validate_config.yml @@ -25,6 +25,8 @@ - {'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': 'matrix_authentication_service_config_captcha_site_key', when: "{{ matrix_authentication_service_config_captcha_service != '' }}"} + - {'name': 'matrix_authentication_service_config_captcha_secret_key', when: "{{ matrix_authentication_service_config_captcha_service != '' }}"} - name: Fail if matrix_authentication_service_config_secrets_encryption is not 64 characters long ansible.builtin.fail: @@ -36,6 +38,11 @@ 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']" +- name: Fail if matrix_authentication_service_config_captcha_service is invalid + ansible.builtin.fail: + msg: "matrix_authentication_service_config_captcha_service must be one of: recaptcha_v2, cloudflare_turnstile, or hcaptcha (or empty, to disable CAPTCHA protection)" + when: "matrix_authentication_service_config_captcha_service not in ['', 'recaptcha_v2', 'cloudflare_turnstile', 'hcaptcha']" + - name: (Deprecation) Catch and report renamed matrix-authentication-service settings ansible.builtin.fail: msg: >- diff --git a/roles/custom/matrix-authentication-service/templates/config.yaml.j2 b/roles/custom/matrix-authentication-service/templates/config.yaml.j2 index 0060584be..efaacc826 100644 --- a/roles/custom/matrix-authentication-service/templates/config.yaml.j2 +++ b/roles/custom/matrix-authentication-service/templates/config.yaml.j2 @@ -72,6 +72,13 @@ account: login_with_email_allowed: {{ matrix_authentication_service_config_account_login_with_email_allowed | to_json }} registration_token_required: {{ matrix_authentication_service_config_account_registration_token_required | to_json }} +{% if matrix_authentication_service_config_captcha_service %} +captcha: + service: {{ matrix_authentication_service_config_captcha_service | to_json }} + site_key: {{ matrix_authentication_service_config_captcha_site_key | to_json }} + secret_key: {{ matrix_authentication_service_config_captcha_secret_key | to_json }} +{% endif %} + clients: {{ matrix_authentication_service_config_clients | to_json }} {% if matrix_authentication_service_config_upstream_oauth2_providers | length > 0 %}