> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# reCAPTCHA

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

> [!NOTE]
>
> This feature is developed by [ayaka-notes/ayakaleaf-pro](https://github.com/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](https://www.google.com/recaptcha/admin), 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`:

```text theme={null}
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](https://developers.google.com/recaptcha/docs/faq): every check passes and the widget shows a warning, so do not use them in production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.