Cloudflare Turnstile

Cloudflare Turnstile je alternativa ke CAPTCHA, která šetří soukromí a návštěvníky obvykle ověří bez jakékoli hádanky. Frontmail ho používá, aby boti nemohli zneužívat váš public key.

Když má šablona zapnuté Vyžadovat CAPTCHA (Turnstile), musí každý požadavek s public key na ni obsahovat platný token Turnstile. Jinak skončí chybou captcha_required nebo captcha_failed dřív, než vás bude stát kredit. Požadavky s private key (z vašeho serveru) CAPTCHA nepotřebují nikdy.

Jak to funguje

Kde formulář běží	Čí klíče Turnstile	Co uděláte
Váš web	Vaše – bezplatný widget ve vašem vlastním účtu Cloudflare	Vytvoříte widget, oba klíče vložíte do Zabezpečení → Ochrana proti botům (Turnstile) a site key dáte do formuláře.
Mobilní aplikace (@frontmail/react-native)	Sdílený mobilní klíč Frontmailu	Nic – <TurnstileWebView> si klíč načte sám.

Proč pro weby vlastní klíče

Bezplatný tarif Turnstile povoluje 10 hostitelů (hostnames) na widget a 20 widgetů na účet; widget, který funguje na libovolné doméně, nabízí Cloudflare jen v tarifu Enterprise. Jeden klíč Frontmailu by tedy weby všech zákazníků nepokryl. Vlastní widget je zdarma, nastavíte ho zhruba za dvě minuty a funguje jen na doménách, které v něm uvedete – vaši CAPTCHA tak nikdo nepoužije na cizím webu.

1. Vytvořte widget Turnstile v Cloudflare

1. Přihlaste se do dashboardu Cloudflare (stačí bezplatný účet – vaše doména Cloudflare používat nemusí).
2. Otevřete Turnstile a klikněte na Add widget.
3. Pojmenujte ho, např. Kontaktní formulář.
4. Přidejte všechny domény, na kterých formulář běží, např. example.com a www.example.com. localhost přidejte jen tehdy, když chcete lokálně zkoušet se skutečnými klíči – pro lokální vývoj se hodí spíš testovací klíče.
5. Widget mode: stačí Managed (zaškrtávací políčko Cloudflare ukáže, jen když si není jistý).
6. Klikněte na Create a zkopírujte Site Key (klíč webu) a Secret Key (tajný klíč).

2. Vložte klíče do Frontmailu

1. V dashboardu Frontmailu otevřete Zabezpečení a najděte kartu Ochrana proti botům (Turnstile).
2. Vložte site key a secret key a klikněte na Uložit klíče.
3. Frontmail secret key hned ověří u Cloudflare – špatný klíč odmítne se srozumitelnou hláškou. Uloží ho šifrovaně a už ho nikdy nezobrazí. Klíče můžete kdykoli vyměnit tlačítkem Vyměnit klíče nebo smazat tlačítkem Odebrat klíče.
4. Po uložení klikněte na Zapnout CAPTCHA u všech šablon a CAPTCHA se zapne u všech stávajících šablon najednou. Šablony použité jako automatická odpověď se přeskočí – ty odesílá Frontmail, ne váš formulář.

Nové šablony pak mají CAPTCHA zapnutou automaticky. Šablony vytvořené dřív, než jste klíče přidali, ji mají vypnutou – zapněte ji tlačítkem výše, nebo u jednotlivých šablon v editoru v Nastavení → Ochrana.

Bez klíčů vám editor šablony CAPTCHA zapnout nedovolí a odkáže vás na stránku Zabezpečení. Výjimkou je zapnuté Povolit mobilní aplikace: pak ji zapnout jde (s upozorněním), protože mobilní aplikace používají sdílený klíč Frontmailu – požadavky z webů na takovou šablonu ale budou končit chybou captcha_not_configured, dokud klíče nepřidáte.

3. Přidejte widget do formuláře

Použijte svůj site key (je veřejný – secret key Frontmail nikdy nevydá). Karta Kód pro web v editoru šablony už widget s vaším site key obsahuje, pokud šablona CAPTCHA vyžaduje.

S čistým HTML a sendForm – vykreslete widget uvnitř formuláře. Turnstile přidá skryté pole cf-turnstile-response, které sendForm odešle automaticky:

<form id="contact">
  <!-- vaše pole -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button>Odeslat</button>
</form>

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

S komponentami pro frameworky – předejte site key komponentě FrontmailForm a ta načte Turnstile, vykreslí widget, odešle token a widget po odeslání resetuje:

• React a Svelte: <FrontmailForm turnstileSiteKey="YOUR_TURNSTILE_SITE_KEY" …>
• Vue: <FrontmailForm turnstile-site-key="YOUR_TURNSTILE_SITE_KEY" …>

Se send() – widget vykreslete sami a token předejte v options:

await send('svc_01J9…', 'tpl_contact', params, { turnstileToken: token });

Přes REST API předejte turnstile_token v JSON těle, nebo cf-turnstile-response v multipart formulářích.

Jak Frontmail token ověřuje

Požadavky z webu nesou hlavičku Origin (nebo Referer). Frontmail jejich token ověří vaším secret key a navíc zkontroluje, že Cloudflare widget vyřešil na stejné doméně, ze které požadavek přišel. Token z jiné domény skončí chybou captcha_failed (details.reason: "hostname_mismatch") – proto ve widgetu uveďte všechny domény svého webu.

Mobilní aplikace

@frontmail/react-native žádný site key nepotřebuje. Komponenta <TurnstileWebView> si mobilní site key Frontmailu načte z GET /v1/public-config (s cache) a widget zobrazí jako vloženou stránku s adresou https://mobile.frontmail.dev. Nativní požadavky nemají hlavičku Origin. Zapněte Povolit mobilní aplikace – bez toho se takové požadavky odmítnou ještě před kontrolou CAPTCHA (i když nemáte nastavené žádné povolené weby). Teprve pak je Frontmail ověří svým sdíleným mobilním tajným klíčem; u organizace, která mobilní aplikace nepovolila, se CAPTCHA proti sdílenému, veřejně dostupnému widgetu nikdy neověřuje.

Vlastní klíč v aplikaci

Vlastní widget můžete použít i v aplikaci: předejte komponentě <TurnstileWebView> siteKey a baseUrl, jehož doména je ve vašem widgetu uvedená (např. https://example.com). SDK pak požadavek automaticky označí turnstile_key: "org" a Frontmail ho ověří vaším secret key.

Jiní nativní klienti (Flutter, Swift, Kotlin…), kteří volají REST API přímo, to mohou udělat stejně: vykreslí váš widget ve WebView a spolu s turnstile_token pošlou turnstile_key: "org".

Lokální vývoj

Cloudflare zveřejňuje testovací klíče, které fungují offline a na jakékoli doméně:

Klíč	Hodnota	Výsledek
Site key	1x00000000000000000000AA	Vždy projde
Secret key	1x0000000000000000000000000000000AA	Vždy projde
Secret key	2x0000000000000000000000000000000AA	Vždy selže

Frontmail je v Zabezpečení → Ochrana proti botům (Turnstile) přijme ve vývojových prostředích.

V produkci testovací klíče odmítáme

Testovací klíče pustí každý požadavek – ochranu tím vypnete. Produkční služba je proto neuloží (400, details.reason: "test_keys") a šablona organizace, která má testovací secret pořád uložený, končí chybou captcha_not_configured (details.reason: "test_secret"), dokud nepřidáte klíče skutečného widgetu.

V automatizovaných testech můžete také odesílat s private key – požadavky s ním kontrolu přeskakují.

Tokeny

• Token platí zhruba 5 minut a lze ho použít jen jednou.
• Po každém odeslání (úspěšném i neúspěšném) widget před dalším pokusem resetujte (turnstile.reset()). Komponenty pro frameworky to dělají automaticky.
• Opakované pokusy SDK o totéž logické odeslání používají stejný idempotency key. Na opakovaný požadavek, který už byl přijat, Frontmail odpoví výsledkem prvního pokusu ještě před kontrolou Turnstile, takže použitý token opakování neshodí.

Chyby

Kód	Status	Kdy	Řešení
captcha_required	403	Šablona vyžaduje CAPTCHA a požadavek nemá token.	Přidejte widget do formuláře, nebo předejte turnstileToken.
captcha_failed	403	Cloudflare token odmítl – je neplatný, vypršel, už byl použit, nebo byl vyřešen na jiné doméně (hostname_mismatch).	Resetujte widget a zkuste to znovu; do widgetu přidejte všechny své domény.
captcha_not_configured	403	Požadavek z webu na šablonu se zapnutou CAPTCHA, ale organizace nemá klíče Turnstile (v produkci ani jiné než testovací klíče Cloudflare).	Přidejte klíče skutečného widgetu v Zabezpečení → Ochrana proti botům (Turnstile).

Vypnutí

Vyžadovat CAPTCHA (Turnstile) můžete vypnout u jednotlivých šablon v editoru šablony v Nastavení → Ochrana – například u šablon, které se odesílají jen z vašeho serveru. U veřejných formulářů důrazně doporučujeme nechat ji zapnutou.

V dashboardu

Klíče najdete v Nastavení zabezpečení, nastavení šablony popisuje Editor šablon.