Přechod z reCAPTCHA na Turnstile: výměna skriptu sama formulář neochrání

Při přechodu z reCAPTCHA na Cloudflare Turnstile změňte klientskou část formuláře i ověření na serveru. Data zpracujte teprve po úspěšné odpovědi služby Siteverify: dokumentace Cloudflare k ověření tokenu výslovně uvádí, že samotný widget formulář nechrání. Správně zobrazený widget tedy ještě neznamená, že server odeslání prověřil.

Nejdřív zjistěte, kterou verzi reCAPTCHA používáte. Migrační postup Cloudflare omezuje kompatibilní režim na reCAPTCHA v2 a vyžaduje změnu serverového ověřovacího volání: Turnstile Siteverify přijímá POST, zatímco původní integrace reCAPTCHA mohla používat GET. Samotné přepnutí skriptu proto nestačí.

Zmapujte formulář a režim reCAPTCHA

Najděte každé místo, kde se před odesláním používá reCAPTCHA: kontaktní formulář, registraci, přihlášení i případné vlastní API. U každé cesty zjistěte, jak se vykresluje widget, odkud se bere token, jak se dostane do požadavku a který serverový kód rozhoduje o jeho přijetí. Pokyny Google k integraci reCAPTCHA začínají registrací webu; při inventuře dohledáte také údaje přidělené původní integraci.

Rozlište viditelnou reCAPTCHA v2 od jejího neviditelného režimu. Kompatibilní režim Turnstile zachovává podporu volání render() a u neviditelné reCAPTCHA v2 také execute(). Pokud server rozhoduje podle skóre reCAPTCHA v3, nejde o přímou výměnu v tomto režimu: před změnou klienta musíte určit novou podmínku pro přijetí požadavku. Zaznamenejte rovněž všechny cesty, které obsluhují stejnou akci, aby některá z nich nezůstala bez kontroly tokenu.

První fáze: připravte serverové rozhodnutí

V testovacím prostředí vytvořte widget Turnstile a uložte jeho tajný klíč do serverové konfigurace. Veřejný sitekey patří do stránky, tajný klíč se prohlížeči neposílá. Backend převezme token z odeslaného formuláře a zavolá Turnstile Siteverify metodou POST; v těle požadavku předá secret a response, případně volitelné remoteip. Jde o volání vašeho serveru ke Cloudflare, nikoli o požadavek změnit metodu, kterou návštěvník odesílá vlastní formulář.

Akci formuláře povolte až po odpovědi se success true. Chybějící token, neúspěšné ověření, nečitelná odpověď i nedostupná ověřovací služba musí zastavit zpracování před uložením dat, odesláním zprávy nebo vytvořením účtu. Pokud máte pro formulář určenou doménu či action, porovnejte s očekávanou hodnotou také hostname nebo action v ověřovací odpovědi. Uživateli nabídněte nový pokus; do provozního záznamu lze uložit důvod zamítnutí, nikdy však tajný klíč.

Aktivní ověřovací službu určujte serverovou konfigurací, nikoli hodnotou pole, kterou může odesílatel požadavku změnit. Při přípravě migrace nechte původní větev dostupnou pro návrat, ale pro konkrétní nasazení stanovte právě jednu větev, jejíž úspěch je nutný k provedení akce. Tím se vyhnete situaci, kdy nový widget funguje na stránce, zatímco stará obslužná cesta přijímá požadavky bez platného ověření.

Druhá fáze: přepněte widget a projděte celý tok

U podporované reCAPTCHA v2 nahraďte původní skript skriptem Turnstile s parametrem compat=recaptcha a vložte nový sitekey. V tomto režimu zůstává název formulářového pole g-recaptcha-response a rozhraní se registruje jako grecaptcha. Zkontrolujte však vlastní JavaScript a odstraňte souběžné zapisování tokenů původním a novým widgetem do stejného pole.

Projděte cestu od načtení stránky po skutečný výsledek na serveru. Token musí dorazit při běžném odeslání i při odesílání řízeném JavaScriptem; u neviditelného režimu záleží také na pořadí execute(), získání tokenu a odeslání dat. V serverových záznamech ověřte, že volání Siteverify proběhlo před akcí formuláře a že rozhodnutí odpovídá jeho výsledku. Úspěšná animace widgetu ani potvrzení zobrazené prohlížečem tuto kontrolu nenahrazují.

Čtyři scénáře pro kontrolu odmítnutí

Testujte přes vlastní koncový bod formuláře, ne jen přímým voláním Siteverify. V izolovaném prostředí lze použít odpovídající testovací sitekey a tajný klíč; produkční tajný klíč testovací tokeny odmítá. Před nasazením projděte také skutečné odeslání s produkční konfigurací na povolené doméně. U každého pokusu sledujte nejen odpověď prohlížeči, ale i to, zda nastala zamýšlená akce.

1. Platný čerstvý token: ověření uspěje a formulář provede zamýšlenou akci. Záznam na serveru ukáže úspěšnou odpověď Siteverify před jejím provedením.
2. Neplatný nebo chybějící token: odešlete náhodný řetězec a samostatně požadavek bez pole s tokenem. Obě odeslání musí skončit bez vedlejšího účinku.
3. Opakovaný token: po úspěšném odeslání zopakujte stejný požadavek se stejným tokenem. Token je jednorázový; další odeslání nesmí znovu spustit akci.
4. Expirovaný token: zachyťte konkrétní token a odešlete jej až po více než pěti minutách bez jeho obnovení. Pouhé ponechání stránky otevřené není spolehlivý test, protože widget může token automaticky obnovit.

U opakovaného či expirovaného tokenu se může objevit kód timeout-or-duplicate. Rozhodující je zamítnutí požadavku serverem, nikoli přesné znění chyby pro uživatele. Nasimulujte také nedostupnost Siteverify: formulář musí odmítnout akci a umožnit nový pokus s čerstvým tokenem, až bude ověřování znovu dostupné.

Nasazení a bezpečný návrat

Klienta a backend přepínejte jako jeden celek, nejprve na omezeném okruhu formulářů. Po nasazení sledujte úspěšná a neúspěšná ověření, chyby volání Siteverify i zprávy od uživatelů, kterým se formulář nedaří odeslat. Každou novou cestu k odeslání prověřte stejnými testy, protože správné chování jednoho formuláře nevypovídá o ostatních.

Pro návrat mějte připravenou původní klientskou integraci, její odpovídající serverové ověření a potřebné klíče. Rollback musí vrátit obě části zároveň: původní token nelze ověřovat tajným klíčem Turnstile a nový widget nemá směřovat na staré ověřování reCAPTCHA. Po návratu zopakujte alespoň odeslání s platným a chybějícím tokenem. Obě zkoušky společně ukážou, že formulář opět přijímá oprávněná odeslání a stále zastavuje ta neověřená.