Features

Requirements

Installing

Configuring

Updating

Uninstalling

Troubleshooting

Support

Cloudflare Turnstile

(for phpBB)

A phpBB 3.3.x extension that integrates Cloudflare Turnstile as a CAPTCHA provider for registration, login, and guest posting, for modern bot protection.

Current Version:
1.2.6

Download Extension

( File Size: 66 KB )

Features

This extension provides registration, login, and guest posting protection with Cloudflare Turnstile.

  • Registration Protection: Turnstile as a selectable CAPTCHA in ACP → Spambot countermeasures
  • Login Protection: When Turnstile is the board CAPTCHA, choose when to require verification:
    • After failed attempts
    • Always
    • Off
  • Guest Posting Protection: Turnstile for Guest posts via ACP → Spambot countermeasures
  • Widget Types: Visible or Invisible mode
  • Widget Theme: Light, Dark, or Auto
  • Widget Size: Scalable widget (100%, 80%, 60%) for registration and login forms
  • ACP Live Preview: Real-time widget preview in extension settings
  • Fail-Safe Options: Configurable behaviour when Cloudflare API is unreachable or errors:
    • Fail-closed: Block submission (secure, may deny legitimate users)
    • Fail-open: Allow submission (may allow bots through)
  • Logging: API errors logged to phpBB admin log
  • Update Notifications: Automatic update checks with ACP notices and optional email alerts (since this is a security-focused extension, staying current matters)
  • Multi-language Support: English, German, French, Spanish, and Italian

Requirements

  • phpBB 3.3.0 or newer (up to 4.0.0)
  • PHP 7.4.0 or newer
  • Cloudflare account with Turnstile site key and secret key

Installing

Download the latest release

  1. Extract the ZIP contents into your phpBB ext/ directory
  2. Your folder structure should be: ext/icecorp/turnstile/
  3. Go to ACP → Customise → Manage extensions
  4. Find Cloudflare Turnstile and click Enable

Configuring

Get Cloudflare Turnstile Keys

  1. Log into your Cloudflare Dashboard
  2. Go to Cloudflare Dashboard → Protect & Connect → Turnstile
  3. Add a new Turnstile widget
  4. Widget Mode: Set to Managed (recommended) or Non-Interactive. Do not select “Invisible” — this overrides the extension’s visibility settings and hides the widget regardless of your extension configuration.
  5. Copy your Site Key and Secret Key

Configure the Extension

Via ACP → Customise → Extensions → Cloudflare Turnstile:

  • Site Key: Your Cloudflare Turnstile site key
  • Secret Key: Your Cloudflare Turnstile secret key (keep confidential)
  • Widget Type: Visible (users see widget) or Invisible (runs in background)
  • Widget Theme: Auto (system preference), Light, or Dark
  • Widget Size: Scale the widget — 100% (default), 80%, or 60%. Applies to registration and login pages; quick login uses a fixed smaller size.
  • API Failure Behaviour: Fail closed (secure) or Fail open (available)
  • Enable Update Checking: Turn automatic version checks on/off (checks every 24 hours)
  • Email Notifications: Send email to board admin when updates are available

A live preview of the widget appears in the settings page when a valid site key is configured, showing the current theme and size settings.

Note: Automatic checks run approximately every 24 hours via phpBB’s cron system, which triggers on page visits by default. If Run periodic tasks from system cron is “enabled” in ACP → Server settings, ensure your system cron runs bin/phpbbcli.php cron:run regularly.

Registration Protection

  1. Go to ACP → General → Board configuration → Spambot countermeasures
  2. Select Cloudflare Turnstile as the spambot countermeasures plugin
  3. Click Submit

Login Protection

  • After failed attempts: Turnstile appears once a user exceeds “Maximum number of login attempts per username” (set in ACP → General → Board configuration → Spambot countermeasures).
  • Always: Turnstile on every login attempt. Requires “Maximum number of login attempts per username” to be set to 0 (any other value causes login to fail after the threshold).
  • Off: Requires Login Protection set to “After failed attempts” and “Maximum number of login attempts per username” to 0.

Note: After failed attempts and Always both require Cloudflare Turnstile to be selected as the board CAPTCHA.

Guest Posting Protection

  1. Go to ACP → General → Board configuration → Spambot countermeasures
  2. Set Enable spambot countermeasures for guest postings to Enabled
  3. Ensure Cloudflare Turnstile is selected as the plugin

Updating

Download the latest release

  1. Go to ACP → Customise → Manage extensions
  2. Disable Cloudflare Turnstile
  3. Delete the ext/icecorp/turnstile/ folder via FTP/File Manager
  4. Extract the new ZIP contents into your phpBB ext/ directory
  5. Your folder structure should be: ext/icecorp/turnstile/
  6. Enable the extension
  7. Purge the cache

Uninstalling

Important: You must change the CAPTCHA setting before disabling the extension.

  1. Go to ACP → General → Board configuration → Spambot countermeasures
  2. Change the plugin to a different option (e.g., “No CAPTCHA” or “Q&A”)
  3. Click Submit
  4. Go to ACP → Customise → Manage extensions
  5. Click Disable for Cloudflare Turnstile
  6. Click Delete data to remove all extension data
  7. Delete the ext/icecorp/turnstile/ folder via FTP/File Manager

Troubleshooting

Locked out of login?

If you have Login Protection set to “Always” and API Failure Behaviour set to “Fail closed” (the default), you can get locked out if your Turnstile keys become invalid or Cloudflare’s API is unreachable.

To recover, run one of these SQL queries via phpMyAdmin or command line:

Disable login protection:

UPDATE phpbb_config SET config_value = '0' WHERE config_name = 'icecorp_turnstile_login_mode';

Or switch to fail-open mode:

UPDATE phpbb_config SET config_value = '1' WHERE config_name = 'icecorp_turnstile_fail_mode';

(Adjust phpbb_ prefix if your database uses a different table prefix.)

Widget not showing?

If you’ve set Widget Type to “Visible” in the extension but the widget doesn’t appear, check your Cloudflare Turnstile widget settings.

In the Cloudflare dashboard, Widget Mode must be set to Managed or Non-Interactive. If it’s set to “Invisible”, the widget will be hidden regardless of your extension settings — Cloudflare’s Invisible mode overrides the extension’s visibility configuration.

To fix: Go to Cloudflare Dashboard → Protect & Connect → Turnstile → Edit your widget → Change Widget Mode to Managed (recommended) → Save.

Can’t log in after maximum attempts?

If you have Login Protection set to “Always” and phpBB’s Maximum number of login attempts is above 0, login will fail once that threshold is reached, even with a solved Turnstile and the correct password.

In Always mode the extension already checks Turnstile. After the threshold, phpBB checks the same token again. Turnstile tokens are one-use, so that second check fails and the password is never reached. Login works again once phpBB’s attempt window expires.

To fix: Go to ACP → General → Board configuration → Spambot countermeasures → set Maximum number of login attempts to 0.

Support

phpBB.com Extensions in Development: [3.3][BETA] Cloudflare Turnstile

Changelog available in above phpBB.com link.

Feel free to reach out with feedback and questions using the form below.


License

GNU General Public License v2.0