Slavi Pantaleev
de1ba73f40
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>
3.3 KiB
(Adapted from the upstream project)
Overview
Captcha can be enabled for this home server. This file explains how to do that.
The captcha mechanism used is Google's ReCaptcha. This requires API keys from Google. If your homeserver is Dendrite then hCapcha can be used instead.
If you are using Matrix Authentication Service, captcha is configured there instead (it handles registration), and Cloudflare Turnstile is supported as well. See Matrix Authentication Service below.
ReCaptcha
Getting keys
Requires a site/secret key pair from:
http://www.google.com/recaptcha/admin
Must be a reCAPTCHA v2 key using the "I'm not a robot" Checkbox option
Setting ReCaptcha keys
Once registered as above, add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:
# for Synapse
matrix_synapse_enable_registration_captcha: true
matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
# for Dendrite
matrix_dendrite_client_api_enable_registration_captcha: true
matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
hCaptcha
Getting keys
Requires a site/secret key pair from:
https://dashboard.hcaptcha.com/sites/new
Setting hCaptcha keys
matrix_dendrite_client_api_enable_registration_captcha: true
matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
matrix_dendrite_client_api_recaptcha_siteverify_api: 'https://hcaptcha.com/siteverify'
matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api.js'
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 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, Cloudflare Turnstile and hCaptcha. 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:
# 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'