Update CAPTCHA documentation to mention turning off verify origin feature (#10046)

* Update CAPTCHA documentation to mention turning off verify origin

Signed-off-by: Aaron Raimist <aaron@raim.ist>
This commit is contained in:
Aaron Raimist 2021-05-26 04:55:30 -05:00 committed by GitHub
parent 557635f69a
commit 3e1beb75e6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 27 additions and 20 deletions

1
changelog.d/10046.doc Normal file
View file

@ -0,0 +1 @@
Update CAPTCHA documentation to mention turning off the verify origin feature. Contributed by @aaronraimist.

View file

@ -1,31 +1,37 @@
# Overview # Overview
Captcha can be enabled for this home server. This file explains how to do that. A captcha can be enabled on your homeserver to help prevent bots from registering
The captcha mechanism used is Google's ReCaptcha. This requires API keys from Google. accounts. Synapse currently uses Google's reCAPTCHA service which requires API keys
from Google.
## Getting keys ## Getting API keys
Requires a site/secret key pair from:
<https://developers.google.com/recaptcha/>
Must be a reCAPTCHA v2 key using the "I'm not a robot" Checkbox option
## Setting ReCaptcha Keys
The keys are a config option on the home server config. If they are not
visible, you can generate them via `--generate-config`. Set the following value:
1. Create a new site at <https://www.google.com/recaptcha/admin/create>
1. Set the label to anything you want
1. Set the type to reCAPTCHA v2 using the "I'm not a robot" Checkbox option.
This is the only type of captcha that works with Synapse.
1. Add the public hostname for your server, as set in `public_baseurl`
in `homeserver.yaml`, to the list of authorized domains. If you have not set
`public_baseurl`, use `server_name`.
1. Agree to the terms of service and submit.
1. Copy your site key and secret key and add them to your `homeserver.yaml`
configuration file
```
recaptcha_public_key: YOUR_SITE_KEY recaptcha_public_key: YOUR_SITE_KEY
recaptcha_private_key: YOUR_SECRET_KEY recaptcha_private_key: YOUR_SECRET_KEY
```
In addition, you MUST enable captchas via: 1. Enable the CAPTCHA for new registrations
```
enable_registration_captcha: true enable_registration_captcha: true
```
1. Go to the settings page for the CAPTCHA you just created
1. Uncheck the "Verify the origin of reCAPTCHA solutions" checkbox so that the
captcha can be displayed in any client. If you do not disable this option then you
must specify the domains of every client that is allowed to display the CAPTCHA.
## Configuring IP used for auth ## Configuring IP used for auth
The ReCaptcha API requires that the IP address of the user who solved the The reCAPTCHA API requires that the IP address of the user who solved the
captcha is sent. If the client is connecting through a proxy or load balancer, CAPTCHA is sent. If the client is connecting through a proxy or load balancer,
it may be required to use the `X-Forwarded-For` (XFF) header instead of the origin it may be required to use the `X-Forwarded-For` (XFF) header instead of the origin
IP address. This can be configured using the `x_forwarded` directive in the IP address. This can be configured using the `x_forwarded` directive in the
listeners section of the homeserver.yaml configuration file. listeners section of the `homeserver.yaml` configuration file.