← Všechny produkty

Turnstile

Turnstile je widget společnosti Cloudflare, který návštěvníkovi vystaví token, jakmile jeho prohlížeč projde sadou neinteraktivních kontrol. Backend webu pak token ověří přes API siteverify. Tato stránka popisuje režimy widgetu, životní cyklus tokenu, dokumentované limity a požadavky na integraci.

Řízení dokumentu

Dana
Technická redaktorka, Integrity Czech Republic s.r.o.

Přehled

Turnstile je mechanismus výzev pro webové formuláře a endpointy. Interaktivní hádanku nahrazuje sadou kontrol, které proběhnou v prohlížeči návštěvníka. Po úspěchu vznikne token a web jej ze svého backendu odešle na endpoint siteverify od Cloudflare, aby potvrdil, že výzva byla pro daný web splněna.

Turnstile můžete použít na libovolném webu. Web nemusí být směrován přes proxy Cloudflare a není potřeba žádný plán zóny Cloudflare.

Cloudflare uvádí, že Turnstile nepředkládá žádné obrázky ani text k rozluštění (https://developers.cloudflare.com/turnstile/, staženo 2026-08-28). V režimu Managed může být návštěvník požádán o jedinou interakci, například o zaškrtnutí políčka. Údaje o tom, jaká část návštěvníků interakci uvidí, se liší web od webu a neuvádíme je zde; míru vyřešení pro konkrétní nasazení najdete v analytice widgetu.

Tvrzení o vlivu složitosti formuláře na konverzní poměr platí vždy jen pro konkrétní web a závisejí na způsobu měření. Žádné takové číslo zde neuvádíme. Pokud je to pro vás podstatné, změřte si míru dokončení na vlastních formulářích před nasazením a po něm.

Architektura

Nasazení Turnstile má tři části:

1. Widget. Malá JavaScriptová komponenta vložená do stránky a nastavená veřejným sitekey. Ověření provádí přímo v prohlížeči: výpočetní úlohy proof of work v JavaScriptu, kontroly konzistence prostředí prohlížeče a behaviorální signály. Nevyžaduje, aby web běžel za Cloudflare.
2. Token. Při úspěchu widget zapíše token do formuláře nebo jej vrátí přes callback. Token je tvrzení, že ověření proběhlo úspěšně pro konkrétní sitekey.
3. Ověření na straně serveru. Backend odešle token spolu s tajným klíčem metodou POST na https://challenges.cloudflare.com/turnstile/v0/siteverify. Odpověď udává úspěch nebo neúspěch spolu s chybovými kódy a obsahuje hostname a časové razítko výzvy. Teprve po úspěšné validaci smí backend odeslanou akci přijmout.

Bezpečnostní záruku dává až krok na straně serveru. Token, který v požadavku sice je, ale nikdo ho neověří, nedokazuje nic, protože tělo požadavku má pod kontrolou klient. Cloudflare uvádí, že token platí 300 sekund a ověřit ho lze jednou; druhé ověření téhož tokenu selže (https://developers.cloudflare.com/turnstile/get-started/server-side-validation/, staženo 2026-08-28). idempotency_key můžete zadat v případech, kdy je potřeba tentýž token ověřit znovu v rámci opakovaného pokusu.

V zónách proxovaných přes Cloudflare umí Turnstile navíc vydat pre-clearance. Návštěvník, který prošel widgetem, pak po dobu platnosti clearance nedostane další výzvu od pravidel WAF ani Bot Management.

Možnosti

Model konfigurace

Konfiguračním objektem je samotný widget: identifikuje ho sitekey a patří k němu secret key. Nastavení widgetu zahrnuje:

• Režim. Managed, non-interactive nebo invisible.
• Hostname. Domény, na kterých se widget smí vykreslit. Hostname se vrací v odpovědi validace a backend by jej měl kontrolovat.
• Vynucení domény. Zda se validace hostname uplatňuje striktně.
• Pre-clearance. Zda widget vydává clearance a v jakém rozsahu.
• Vzhled a spouštění. Zda se widget vykresluje vždy, nebo jen když je potřeba interakce, a zda se ověření spustí při vykreslení, nebo až na vyžádání.

Mezi parametry na straně klienta, které se nastavují pro každou instanci, patří action, tedy popisek určující, který formulář token vytvořil, a cdata, tedy neprůhledná hodnota vracená v odpovědi validace. Obě hodnoty vrací siteverify a obě je třeba kontrolovat, protože vážou token ke konkrétní operaci, pro kterou byl vydán.

Cloudflare zveřejňuje testovací sitekeys a tajné klíče, které vždy projdou, vždy selžou nebo vždy vyžadují interakci. V automatizovaných testech je používejte a ověřování v testovacím prostředí nevypínejte, protože vypnutá větev ověřování se často dostane až do produkce.

Limity a omezení

Dokumentované limity, ověřeno 2026-08-31 podle https://developers.cloudflare.com/turnstile/plans/:

Chování tokenu podle https://developers.cloudflare.com/turnstile/get-started/server-side-validation/, staženo 2026-08-28: token platí 300 sekund a ověřit jej lze pouze jednou, pokud není zadán idempotency_key.

Další omezení:

• Cloudflare měsíční kvótu pro požadavky na siteverify nezveřejňuje. Nenavrhujte proto řešení podle žádného konkrétního měsíčního čísla a každý takový údaj z jiných zdrojů berte jako neověřený.
• Vyšší limity widgetů a hostname, než jsou standardní hodnoty, vyžadují smlouvu Enterprise. Většina nasazení narazí nejdřív na limit 10 hostname na widget, protože domény časem přibývají.
• Turnstile chrání konkrétní endpointy, na kterých se widget vykresluje a na kterých se ověřuje token. Endpointy bez widgetu, včetně mobilních API a starších cest, zůstávají bez této ochrany.
• Widget vyžaduje v prohlížeči JavaScript. Klienti, kteří JavaScript nespouštějí, token nezískají, takže endpoint, který je musí obsloužit, potřebuje jiné ochranné opatření.
• Klienti bez prohlížeče, včetně serverových konzumentů API, výzvu dokončit nedokážou. Turnstile proto nedávejte před koncový bod určený pro komunikaci mezi stroji.
• Pre-clearance funguje jen tam, kde je chráněný web proxovaný přes Cloudflare.
• Turnstile vrací rozhodnutí o relaci prohlížeče. Neověřuje totožnost uživatele ani nepotvrzuje, že je odeslaný obsah legitimní.
• Tvrzení o ochraně soukromí a o souladu s předpisy pro konkrétní nasazení závisejí na tom, jak web zpracovává data kolem widgetu, a na příslušném právním posouzení. Produktová dokumentace nemůže soulad za provozovatele webu doložit. Vhodným podkladem pro takové posouzení jsou vlastní vyjádření Cloudflare o datech, která Turnstile sbírá.

Dostupnost podle plánu

Nasazení

Předpoklady.

• Určete, které endpointy jsou zneužívány a čím to doložíte: falešné registrace, pokusy o credential stuffing, spam v komentářích nebo kontaktních formulářích, zneužívání kupónů a voucherů.
• Určete všechny služby, které dotčená odeslání přijímají. Jeden formulář často odesílá data do několika backendů a token musí ověřit každý z nich, který odeslaná data přijímá.
• Poznamenejte si, které z těchto endpointů volají i klienti mimo prohlížeč, protože ti výzvu dokončit nedokážou.
• Zaznamenejte výchozí metriky: počet odeslání, míru dokončení a metriku zneužití určenou výše.
• Zjistěte, kterou stávající integraci CAPTCHA chcete nahradit a které části kódu na ni odkazují.
• Určete, kde bude secret key uložen, a ověřte, že není v žádném klientském balíčku ani repozitáři.

Ověřování po fázích. Turnstile nejdřív nasaďte na jediný endpoint s jasným signálem zneužití. Widget a serverovou validaci zaveďte společně a po úvodní dobu výsledky validace pouze logujte, aniž byste odeslané formuláře odmítali. Sledujte, jaký podíl odeslání přichází s platným tokenem, s neplatným tokenem a zcela bez tokenu. Než začnete vynucovat, ověřte pomocí testovacích klíčů Cloudflare, že chybová větev odmítá správně.

Konfigurace.

1. Vytvořte jeden widget pro každou logickou aplikaci, ne pro každý formulář, a nastavte mu hostname.
2. Nastavte action pro každý formulář zvlášť, aby šlo tokeny přiřadit, a ověřte ji v odpovědi validace.
3. Serverové ověřování zaveďte v každé službě, která přijímá chráněné odeslání. Chybějící nebo neplatný token berte jako důvod k odmítnutí.
4. Zkontrolujte hostname a action v odpovědi siteverify, nejen success.
5. Režim widgetu volte podle formuláře: invisible nebo non-interactive tam, kde to míra zneužívání dovolí, a managed tam, kde ne.
6. V klientovi ošetřete callbacky pro vypršení tokenu a pro chyby. Návštěvník, kterému vyplnění formuláře trvá déle, tak dostane nový token místo nevysvětlené chyby.
7. Pokud web běží přes proxy Cloudflare, zapněte pre-clearance a Turnstile zkombinujte s rate limiting rules, případně, máte-li na ně licenci, i s bot rules.
8. Předchozí integraci CAPTCHA a její klíče odstraňte až po ověření nové cesty.

Přepnutí. Odmítání nevalidovaných odeslání zapínejte vždy jen na jednom endpointu a v každém kroku sledujte míru dokončení. Původní opatření ponechte v provozu, dokud endpoint neověříte, a teprve potom je odstraňte.

Ověření.

• Ověřte, že odeslání bez tokenu backend odmítne. Testujte přímo proti endpointu, ne přes formulář.
• Ověřte, že opakovaně použitý token je při druhém použití odmítnut.
• Ověřte, že se secret key neobjevuje v žádném souboru na straně klienta.
• Ověřte, že míra dokončení u chráněných formulářů nevybočila z obvyklého rozmezí.
• Ověřte, že se metrika zneužití zaznamenaná v rámci předpokladů změnila očekávaným směrem, a zkontrolujte, zda se aktivita nepřesunula na sousední endpoint.
• Ověřte chování v prohlížečích a asistivních technologiích, které máte v matici podporovaných platforem.

Vrácení změn. Vypněte vynucování v backendu, čímž se bez nasazení frontendu obnoví původní chování při přijímání požadavků, a widget nechte dál vykreslovat, dokud příčinu nevyšetříte. Kód původního opatření si ponechte, dokud se nasazení nepotvrdí jako stabilní.

Provozní aspekty

Sledujte u každého widgetu míru vyřešených výzev a míru neúspěšných validací. Nárůst neúspěšných validací obvykle neznamená více útoků, ale chybu na straně klienta, vypršený token u dlouhého formuláře nebo změnu v postupu odeslání formuláře.

Po nasazení sledujte, kam se aktivita přesune. Jakmile se útok na chráněný formulář prodraží, útočníci obvykle přejdou na nechráněný endpoint, například na mobilní API nebo na starší cestu. Zahrňte proto tyto endpointy do kontroly.

Tajný klíč rotujte podle pevného harmonogramu a po každém incidentu, který se týkal backendu. Ukládejte ho spolu s ostatními tajnými údaji, ne do konfiguračních souborů.

Při návrhu vícekrokových formulářů myslete na platnost tokenu. Token vydaný na začátku dlouhého procesu může mít při odeslání formuláře platnost 300 sekund už za sebou. V takovém případě výzvu před odesláním spusťte znovu.

Sledujte, kolik hostname je u každého widgetu nastaveno, a porovnávejte to s dokumentovaným limitem, protože přidání domény k widgetu, který limit vyčerpal, selže už při konfiguraci, ne až za běhu.

Počítejte s těmito způsoby selhání: nasazení frontendu, které odstraní pole s tokenem; nasazení backendu, které přestane volat siteverify; změna content security policy, která zablokuje skript widgetu; a seznam hostname widgetu, ve kterém chybí nově přidaná doména nebo který dosáhl zdokumentovaného maxima.

Známá omezení

• Widget bez ověření na straně serveru nechrání vůbec nic. Jde o nejčastější chybu integrace a z uživatelského rozhraní ji nepoznáte, protože formulář se stále zobrazuje i odesílá.
• Kontrola pouze success ignoruje vazbu na hostname a action, takže token získaný na jednom formuláři nebo webu lze po dobu jeho platnosti použít i jinde.
• Tokeny platí 300 sekund a jsou jednorázové, pokud nezadáte idempotency key. Dlouhé formuláře i logika opakovaných pokusů musí počítat s obojím.
• Režim Managed může vyžadovat jedinou interakci, například zaškrtnutí políčka. Obrázkové ani textové hádanky nepoužívá, ale tvrdit, že k žádné interakci nikdy nedojde, není správné.
• Klienti, kteří nespouštějí JavaScript, token nezískají. Týká se to nástrojů pro přístupnost, některých vestavěných prohlížečů i legitimní automatizace.
• Turnstile chrání ty endpointy, kde je nasazen. Je to jedna vrstva ochrany a endpointy bez widgetu zůstávají nechráněné.
• Pre-clearance vyžaduje, aby web běžel v proxy Cloudflare; na weby hostované jinde se nevztahuje.
• Počet widgetů a hostname je omezený: ve standardní úrovni 20 widgetů na účet a 10 hostname na widget. Nasazení, ke kterému postupně přibývají domény, narazí na limit hostname dřív než na kterékoli jiné zdokumentované omezení.

Interoperabilita

V proxované zóně respektují pre-clearance z Turnstile jak vlastní pravidla WAF, tak pravidla Bot Management. Jednou ověřený návštěvník tak po dobu platnosti clearance další výzvu nedostane.

Turnstile lze kombinovat s rate limiting rules, které omezují počet pokusů proti endpointu bez ohledu na výsledek výzvy, a s bot rules, které reagují na klasifikaci provozu. Všechny tři řeší jinou vlastnost a běžně se nasazují společně.

Volání siteverify je běžný požadavek HTTPS a lze ho provést z libovolného backendu, včetně Cloudflare Workeru předřazeného originu. Ověření pak proběhne na edge, a ne až v aplikaci.

Ephemeral IDs, které vrací siteverify, můžete propojit se signály zneužití na straně aplikace, aniž byste ukládali adresu nebo trvalý identifikátor.

Turnstile nezávisí na konfiguraci DNS ani zóny, takže jej nasadíte na weby hostované kdekoli a později, pokud se web přesune, jej spojíte s proxy od Cloudflare.

Časté dotazy

Je volání na straně serveru povinné? Ano. Bez volání siteverify je token jen neověřený údaj dodaný klientem a widget neposkytuje žádnou ochranu.

Jak dlouho je token platný a lze jej ověřit dvakrát? Cloudflare uvádí platnost 300 sekund a jedinou validaci na token. Předejte idempotency_key tam, kde opakovaný pokus musí tentýž token ověřit znovu.

Musí být web na Cloudflare? Ne. Widget i siteverify fungují na libovolném webu. Jedinou funkcí, která vyžaduje, aby web běžel přes proxy Cloudflare, je pre-clearance.

Co obnáší přechod z reCAPTCHA? Widget na straně klienta podporuje implicitní i explicitní vykreslování a na straně serveru se vymění ověřovací endpoint a tajný klíč. Obě strany je nutné změnit společně; původní klíče odstraňte až poté, co novou cestu ověříte.

Použité zdroje

• https://developers.cloudflare.com/turnstile/, staženo 2026-08-28.
• https://developers.cloudflare.com/turnstile/plans/, staženo 2026-08-31.
• https://developers.cloudflare.com/turnstile/concepts/widget/, staženo 2026-08-28.
• https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/, staženo 2026-08-28.
• https://developers.cloudflare.com/turnstile/get-started/server-side-validation/, staženo 2026-08-28.
• https://developers.cloudflare.com/turnstile/concepts/pre-clearance-support/, staženo 2026-08-28.
• https://developers.cloudflare.com/turnstile/concepts/ephemeral-id/, staženo 2026-08-28.
• https://developers.cloudflare.com/turnstile/troubleshooting/testing/, staženo 2026-08-28.

Snímek obsahu: 2026-08-28. Limity znovu ověřeny 2026-08-31.

Přehled změn