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>

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

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'
+```

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                                                               #

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: >-

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 %}