synapse/docs/CAPTCHA_SETUP.md

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

    recaptcha_public_key: YOUR_SITE_KEY
    recaptcha_private_key: YOUR_SECRET_KEY

In addition, you MUST enable captchas via:

    enable_registration_captcha: true

## 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,
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.
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`# Overview`
Update CAPTCHA_SETUP (it continues to ignore fallback, but I guess I should fix it so that doesn't need the key in two different places) 2015-03-30 17:27:42 +00:00			`Captcha can be enabled for this home server. This file explains how to do that.`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00			`The captcha mechanism used is Google's ReCaptcha. This requires API keys from Google.`

(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`## Getting keys`

Modify doc to update Google ReCaptcha terms (#6257) 2019-10-30 12:30:20 +00:00			`Requires a site/secret key pair from:`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`<https://developers.google.com/recaptcha/>`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00
Specify the type of reCAPTCHA key to use (#5013) Signed-off-by: Aaron Raimist <aaron@raim.ist> 2019-05-29 03:04:24 +00:00			`Must be a reCAPTCHA v2 key using the "I'm not a robot" Checkbox option`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`## Setting ReCaptcha Keys`

rename CAPTCHA_SETUP this is rst so name it accordingly 2016-12-01 12:01:54 +00:00			`The keys are a config option on the home server config. If they are not`
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			visible, you can generate them via `--generate-config`. Set the following value:

Modify doc to update Google ReCaptcha terms (#6257) 2019-10-30 12:30:20 +00:00			`recaptcha_public_key: YOUR_SITE_KEY`
			`recaptcha_private_key: YOUR_SECRET_KEY`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`In addition, you MUST enable captchas via:`
rename CAPTCHA_SETUP this is rst so name it accordingly 2016-12-01 12:01:54 +00:00
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`enable_registration_captcha: true`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			`## Configuring IP used for auth`
Add original, unmodified CAPTCHA-SETUP from the webclient repo before modifying (captcha setup is now purely on the HS). 2015-03-30 17:18:19 +00:00
			`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,`
(#5849) Convert rst to markdown (#6040) Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. 2019-09-17 11:55:29 +00:00			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
Update CAPTCHA_SETUP.rst X-Forwarded-For docs It looks like CAPTCHA_SETUP.rst contains information relevant to an old version of Synapse, but Synapse now has a different approach to configuring use of the X-Forwarded-For header. 2017-02-09 05:21:02 +00:00			`listeners section of the homeserver.yaml configuration file.`