magetu / module-turnstile
Registers Cloudflare Turnstile as a native captcha type for Magento Open Source and Adobe Commerce.
Package info
github.com/Magetu/module-turnstile
Type:magento2-module
pkg:composer/magetu/module-turnstile
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
- magento/framework: ^103.0
- magento/module-config: *
- magento/module-customer: *
- magento/module-re-captcha-admin-ui: ^1.1
- magento/module-re-captcha-frontend-ui: ^1.1
- magento/module-re-captcha-ui: ^1.1
- magento/module-re-captcha-validation: ^1.1
- magento/module-re-captcha-validation-api: ^1.1.3
- magento/module-store: *
Requires (Dev)
- phpunit/phpunit: ^9.5 || ^10.5 || ^12.0
Suggests
- magento/module-re-captcha-webapi-ui: Carries the token to the REST-guarded checkout steps (place order, coupon, gift card). Without it those steps are guarded by no captcha type at all. It is not required only because a store with no Knockout checkout never loads it.
Provides
None
Conflicts
None
Replaces
None
README
Adds Cloudflare Turnstile to Magento 2, Adobe Commerce and Mage-OS as a native captcha type, magetu_turnstile.
After you install it, "Cloudflare Turnstile" is offered for every form in Magento's captcha settings, under Stores > Configuration > Security. Pick it for a form, and Magento's own captcha stack checks that form. No page needs extra code.
Turnstile does not send data to Google, and it sets no third-party cookie by default.
Requirements
- Magento Open Source, Adobe Commerce, Adobe Commerce Cloud, or Mage-OS, 2.4.7 to 2.4.9
- PHP 8.1 to 8.5
- Magento's own reCAPTCHA modules (
magento/module-re-captcha-*), installed and enabled
Install
composer require magetu/module-turnstile bin/magento setup:upgrade
If your store removed Magento's reCAPTCHA modules
This module needs them. Undo both of these:
-
Remove any
magento/module-re-captcha-*entries from thereplaceblock of your rootcomposer.json, run composer, and check thatvendor/magento/module-re-captcha-*exists. -
Enable the modules again. They stay disabled in
app/etc/config.phpuntil you do:bin/magento module:status --disabled | grep '^Magento_ReCaptcha' | xargs bin/magento module:enable bin/magento setup:upgrade
If step 2 is missing, saving a form's captcha type fails with The "recaptcha_frontend/type_for/..." path doesn't exist.
Get your keys
- In the Cloudflare dashboard, open Turnstile > Add widget.
- Add your store's hostnames and choose a widget mode (Managed is Cloudflare's default).
- Copy the site key and the secret key.
Create a separate widget for each environment: production, staging, and local.
Configure
Enter the keys in the admin:
- Storefront: Stores > Configuration > Security > Google reCAPTCHA Storefront > Cloudflare Turnstile
- Admin: Stores > Configuration > Security > Google reCAPTCHA Admin Panel > Cloudflare Turnstile
Or with the CLI:
bin/magento config:set recaptcha_frontend/type_magetu_turnstile/public_key "<site key>" bin/magento config:set recaptcha_frontend/type_magetu_turnstile/private_key "<secret key>" bin/magento cache:clean config
Both keys are stored encrypted. Treat the secret key like a database password.
Then, choose Cloudflare Turnstile under "Storefront" (or "Admin Panel") for each form you want to protect.
| Field | What it does | Default |
|---|---|---|
| Turnstile Site Key | Public key, sent to the browser | empty |
| Turnstile Secret Key | Private key, used to verify tokens with Cloudflare | empty |
| Size | Normal, Flexible, or Compact | Flexible |
| Theme | Auto, Light, or Dark | Auto |
| Appearance | Always, Execute, or Interaction Only | Always |
| Language Code | Forces a widget language; empty means auto-detect | empty |
| Send Visitor IP to Cloudflare | Sends the visitor's IP with each check | No |
| Validate Action | Rejects a token made for a different form | Yes |
| Allowed Hostnames | Comma-separated hostnames a token must come from; empty means your store's base URL host | empty |
The widget mode (Managed, Non-interactive, or Invisible) is set on the widget in Cloudflare, not here. To change it, change it in Cloudflare.
Test keys
Cloudflare's public test keys work on any domain, including localhost:
| Site key | Behavior |
|---|---|
1x00000000000000000000AA |
Always passes (visible) |
2x00000000000000000000AB |
Always fails (visible) |
3x00000000000000000000FF |
Forces an interactive challenge |
| Secret key | Behavior |
|---|---|
1x0000000000000000000000000000000AA |
Always passes |
2x0000000000000000000000000000000AA |
Always fails |
3x0000000000000000000000000000000AA |
Always reports "token already spent" |
Supported forms
Every form Magento offers a captcha for: login, register, forgot password, edit account, contact, newsletter, product review, wishlist share, email to a friend, company registration, invitation, coupon and gift card (cart and checkout), the checkout login and authentication popup, place order, and admin login and forgot password.
Hyvä themes are supported through Hyvä's standard reCAPTCHA block names. No theme change is needed.
Known limits
-
Express and wallet buttons (Apple Pay, Google Pay, PayPal express, and similar) that place orders without the normal checkout form are not covered. Test each payment method after you turn on "Place order".
-
Custom or one-page checkouts that move or hide the payment area can leave the widget in a hidden container. An interactive challenge then has nowhere to show. Check that the widget is visible on your checkout, or use an Invisible widget there.
-
Magento's REST place-order guard checks the
payment-informationcall only. Magento does not guard the directPUT .../orderREST routes, whichever captcha type you use. -
Integration-token API calls skip captcha checks. This is Magento's behavior. Admin-token calls are still checked.
-
Tokens are single use. If you write your own AJAX submit for a protected form, reset the widget before a retry:
window.MagetuTurnstile.reset(form). -
PayPal Payflow Pro is wired up but has not been tested on a live store.
-
Admin login: turn Turnstile on for the admin only after the storefront works. If you are locked out, run:
bin/magento config:set recaptcha_backend/type_for/user_login "" --scope=default bin/magento cache:clean config
Uninstall
First, switch every form that uses Cloudflare Turnstile to another type, or to "No". A form that still points at a removed type causes an error on that page.
bin/magento config:set recaptcha_frontend/type_for/<form> "" --scope=default # for each form you set bin/magento cache:clean config
Use config:set (or the admin) to clear a form's type. Writing an empty string straight into the database causes an error on every page that shows that form.
Then remove the module with Magetu_ModuleDataCleanUp (magetu/module-data-cleanup), the recommended way. It also deletes the keys and settings this module saved, and its setup_module record. Add a data patch to one of your own modules, as that module's README shows:
use Magetu\ModuleDataCleanUp\Setup\Patch\AbstractModuleDataCleanUp; class RemoveMagetuTurnstile extends AbstractModuleDataCleanUp { protected string $moduleName = 'Magetu_Turnstile'; /** @var string[] */ protected array $configSectionGroups = [ 'recaptcha_frontend/type_magetu_turnstile/', 'recaptcha_backend/type_magetu_turnstile/', ]; }
Then run:
bin/magento module:disable Magetu_Turnstile composer remove magetu/module-turnstile bin/magento setup:upgrade
License
MIT. See LICENSE.md.