Cloudflare Turnstile Integration

Cloudflare Turnstile is a smart CAPTCHA alternative used to protect the login page from automated abuse and brute-force attacks.

Prerequisites

To enable Turnstile, you need a Cloudflare account.

1. Log in to the Cloudflare Dashboard.
2. Go to Turnstile in the sidebar.
3. Add a new site (widget).
   • Domain: Add your production domain(s) and localhost (for testing).
   • Widget Mode: "Managed" is recommended.
4. Copy the Site Key and Secret Key.

Configuration

The integration is controlled via environment variables. Add the following to your .env file:

Variable	Description	Default
TURNSTILE_ENABLED	Set to True to enable the widget.	False (when DEBUG=True)
TURNSTILE_SITE_KEY	The public key from Cloudflare.	Dummy Key
TURNSTILE_SECRET_KEY	The private key from Cloudflare.	Dummy Key

Example .env

TURNSTILE_ENABLED=True
TURNSTILE_SITE_KEY=0x4AAAAAAAVrT...
TURNSTILE_SECRET_KEY=0x4AAAAAAAVrT...

Production vs. Development

• Development: By default, TURNSTILE_ENABLED is False when DEBUG=True. This allows you to log in easily without the widget. To test the widget locally, set TURNSTILE_ENABLED=True in your .env file.
• Production: Ensure TURNSTILE_ENABLED=True is set, along with your production keys.

Testing

For testing purposes (or if you don't have real keys yet), you can use Cloudflare's dummy keys which always pass or always fail:

• Site Key (Always Pass): 1x00000000000000000000AA
• Secret Key (Always Pass): 1x0000000000000000000000000000000AA

See the official Turnstile testing docs for more dummy keys (e.g., to test failure states).