Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

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

Merged
merged 5 commits into from
May 26, 2021
Merged

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

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
69dea58
Update CAPTCHA documentation to mention turning off verify origin
aaronraimist May 23, 2021
7d529a4
Add changelog
aaronraimist May 23, 2021
7055660
Update docs/CAPTCHA_SETUP.md
aaronraimist May 25, 2021
4212675
Update changelog.d/10046.doc
aaronraimist May 25, 2021
a5d27b7
Change to public_baseurl
aaronraimist May 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/10046.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update CAPTCHA documentation to mention turning off the verify origin feature.
aaronraimist marked this conversation as resolved.
Show resolved Hide resolved
48 changes: 26 additions & 22 deletions docs/CAPTCHA_SETUP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,35 @@
# 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.

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

A captcha can be enabled on your homeserver to help prevent bots from registering
accounts. Synapse currently uses Google's reCAPTCHA service which requires API keys
from Google.

## Getting API keys

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 your server name to the list of authorized domains.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this server name as in server_name as in the thing that ends up in MXIDs, or the public hostname for the C-S API?

I've a feeling it's the latter, in which case it might be better to use words like "the public hostname for your server, as set in public_baseurl in homeserver.yaml".

Copy link
Contributor Author

@aaronraimist aaronraimist May 25, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was just trying to have them put some domain in there because Google requires at least one domain to be added to the list. As long as they do step 9 then it doesn't matter what domains are in the list.

But yes that is probably more correct because someone may not do step 9 and may not have the public_baseurl as a subdomain of the server name domain.

1. Agree to the terms of service and submit
aaronraimist marked this conversation as resolved.
Show resolved Hide resolved
1. Copy your site key and secret key and add them to your `homeserver.yaml`
configuration file
```
recaptcha_public_key: YOUR_SITE_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
```
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

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,
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,
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
listeners section of the homeserver.yaml configuration file.
listeners section of the `homeserver.yaml` configuration file.