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 <noreply@anthropic.com>
This commit is contained in:
Slavi Pantaleev
2026-07-15 07:29:35 +03:00
parent d2f1fa74cc
commit de1ba73f40
5 changed files with 62 additions and 0 deletions
@@ -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 #
@@ -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: >-
@@ -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 %}