reCAPTCHA

How to protect login, registration and password reset with Google reCAPTCHA?

This feature is developed by ayaka-notes/ayakaleaf-pro and is available from v6.4.0.

The email and password login, the LDAP login, registration and password reset can ask for a Google reCAPTCHA v2 (invisible). It is off by default. Most users see nothing: the check runs when they press the button, and Google shows a picture challenge only when it finds the request suspicious. SAML and OIDC logins and accounts created by an admin are not affected.

1. In the reCAPTCHA admin console, create a key of type reCAPTCHA v2, Invisible reCAPTCHA badge, and add the domain of your instance. A domain also covers its subdomains, e.g. example.com covers latex.example.com.
2. Set the two keys in config/variables.env and run bin/up:

RECAPTCHA_SITE_KEY=<site key>
RECAPTCHA_SECRET_KEY=<secret key>

Variable	Default	Purpose
RECAPTCHA_SITE_KEY	Unset	Turns the captcha on for login, LDAP login, registration and password reset.
RECAPTCHA_SECRET_KEY	Unset	Secret key of the same reCAPTCHA key, used by the server to check the answers.
RECAPTCHA_ENDPOINT	https://www.google.com/recaptcha/api/siteverify	Where the server checks the answers. Where www.google.com cannot be reached, use https://www.recaptcha.net/recaptcha/api/siteverify.
CAPTCHA_TRUSTED_USERS	Unset	Comma separated emails the server lets through without checking the captcha.
CAPTCHA_TRUSTED_USERS_REGEX	Unset	A regular expression for such emails; it must match the whole email.
DEVICE_HISTORY_SECRET	Unset	64 hex characters, e.g. from openssl rand -hex 32. Lets a browser that logged in with an email skip the captcha for that email for 90 days. Unset, every login gets the captcha.

• The pages load the reCAPTCHA script from www.recaptcha.net, which also works where www.google.com is blocked.
• Registration and password reset ask every time. The LDAP login also asks every time, also with DEVICE_HISTORY_SECRET: it sends a username, not an email.
• Logins stay rate limited as well: 20 attempts per minute per IP address and 10 attempts per 2 minutes per email.
• Ayakaleaf Pro checks only whether Google accepts the answer. reCAPTCHA v3 scores and thresholds are not supported, and Google decides when to show a challenge.
• To try it before you have a key, use Google’s test keys: every check passes and the widget shows a warning, so do not use them in production.