reCAPTCHA naar Turnstile: v3 vraagt een andere aanpak

Een bestaande reCAPTCHA v2-implementatie kun je via de compatibiliteitsmodus naar Turnstile migreren: Cloudflares migratiehandleiding beschrijft die route voor de zichtbare en onzichtbare variant. Je vervangt de sitekey en geheime sleutel, past de client aan en laat de server tokens bij Turnstile verifiëren.

Bij reCAPTCHA v3 is eerst een ontwerpkeuze nodig. Volgens Googles v3-documentatie levert de verificatie een score en een action op waarmee de applicatie haar beslissing kan bepalen. De compatibiliteitsmodus vertaalt dat scoremodel niet rechtstreeks. Als je huidige code bij een lage score een extra controle start of een aanvraag tegenhoudt, moet je vastleggen hoe die beslissing na de overstap tot stand komt.

Inventariseer formulieren, sleutels en beslisregels

Maak per beschermd formulier een overzicht van de gebruikte reCAPTCHA-variant, de publieke sitekey, de bijbehorende geheime sleutel, de toegestane hostnames en de plek waar de server het token controleert. Noteer ook hoe het token de server bereikt: als formulierveld, via een callback of als onderdeel van een afzonderlijk API-verzoek. Een inlogformulier en een registratieformulier kunnen dezelfde bibliotheek laden, maar verschillende sleutels, acties of serverroutes gebruiken.

Zoek vervolgens in de clientcode naar render- en execute-aanroepen en in de servercode naar het verificatie-endpoint. Leg bij een scoregestuurde implementatie per action vast welke grens en welke vervolgstap nu gelden. Dat maakt zichtbaar waar een eenvoudige sleutelwissel volstaat en waar applicatielogica verandert. Bewaar de bestaande configuratie per omgeving, zodat tijdens de omschakeling duidelijk blijft welke client bij welke verificatieroute hoort.

Migreer zichtbare en onzichtbare reCAPTCHA v2

Maak Turnstile-widgets aan voor de betrokken formulieren. Koppel de nieuwe sitekeys aan de juiste geheime sleutels en gebruik voor ontwikkel-, test- en productieomgevingen de bedoelde configuratie. De geheime sleutel hoort uitsluitend op de server.
Vervang het reCAPTCHA-script door het Turnstile-script met de parameter compat=recaptcha. In deze modus is de API beschikbaar als grecaptcha, werkt impliciete weergave en blijft de naam van het tokenveld g-recaptcha-response.
Vervang de sitekey in de widgetconfiguratie en in eventuele aanroepen van grecaptcha.render(). Controleer bij onzichtbare reCAPTCHA ook de execute-aanroep en de callback die het verkregen token aan de aanvraag toevoegt.
Laat de server het ontvangen token met de nieuwe geheime sleutel bij Turnstile Siteverify controleren. De beschermde handeling mag pas doorgaan nadat de verificatie is geslaagd.

Controleer ook formulieren die pas na het laden van de pagina verschijnen. Hun widget moet worden aangemaakt met de nieuwe sitekey en het token moet terechtkomen bij de serverroute die de bijbehorende geheime sleutel gebruikt. De compatibiliteitsmodus beperkt zo de benodigde wijzigingen aan de client, maar neemt de serverwijziging niet weg.

Ontwerp de route voor reCAPTCHA v3 opnieuw

Vervang een scoregestuurde aanroep door een Turnstile-integratie bij de handeling die je wilt beschermen. Stuur het uitgegeven token met die aanvraag mee. Bij een standaardintegratie kan de server het veld cf-turnstile-response lezen; gebruik je een callback, dan kan de client het token zelf meesturen. Kies één manier per formulier en pas de server daarop aan.

Herzie daarna de beslisregel afzonderlijk van de tokencontrole. Een geslaagde Turnstile-verificatie vertelt de server dat het token geldig is, maar levert geen vervangende v3-score op voor bestaande drempelwaarden. Had een lage score bijvoorbeeld tot een extra identiteitscontrole geleid, dan moet de applicatie bepalen op welke andere grond die controle voortaan start. Een ingestelde Turnstile-action kan helpen om te controleren bij welke handeling het token hoort; die action is geen risicoscore.

Controleer het token en de context op de server

Cloudflares Siteverify-instructies vereisen een POST-verzoek met secret en response en beschrijven een token dat vijf minuten geldig en eenmaal bruikbaar is. Het endpoint accepteert formuliergegevens of JSON. Lees de tokenwaarde uit het veld dat bij de gekozen clientintegratie hoort en gebruik de geheime sleutel van de bijbehorende widget.

Behandel success als noodzakelijke voorwaarde, niet als de volledige formuliercontrole. Vergelijk de geretourneerde hostname met de toegestane hostname voor de omgeving waarin de aanvraag binnenkomt. Als het formulier een action gebruikt, vergelijk dan ook de geretourneerde action met de waarde die de server voor deze handeling verwacht. Bepaal die verwachte waarden in de serverconfiguratie, niet uit een vrij aanpasbaar formulierveld.

Een ontbrekend token, een mislukte verificatie of een onbereikbare verificatiedienst mag de beschermde handeling niet vrijgeven. Na een verlopen of al gebruikt token moet de client een nieuw token verkrijgen; hetzelfde token opnieuw aanbieden lost de fout niet op. Houd geheime sleutels buiten browsercode en gebruikersgerichte foutmeldingen. Geef de gebruiker bij een afgebroken inzending wel een duidelijke mogelijkheid om opnieuw te proberen.

Test de omschakeling en bereid de terugweg voor

Test per formulier de complete keten, van widget tot serverbeslissing. Controleer daarbij zowel de veldnaam als de sleutelconfiguratie: een zichtbaar werkende widget zegt nog niets over de servervalidatie. Neem ten minste deze gevallen op in de test van de betrokken route:

Een geldige inzending met de verwachte hostname en, waar ingesteld, de verwachte action.
Een aanvraag zonder token en een aanvraag met een verlopen of eerder gebruikt token.
Een geldig token waarvan de hostname of action niet overeenkomt met de serverconfiguratie.
Een tijdelijke fout bij Siteverify, gevolgd door een nieuwe inzending met een nieuw token.

Schakel client en server per formulier of samenhangende groep om. Bewaar tijdens de overgang de oude scriptconfiguratie, sleutels, tokenveldnaam en verificatieroute als één terug te zetten geheel. Alleen het script terugzetten terwijl de server bij Turnstile blijft verifiëren, verbreekt de aanvraagketen. Verwijder oude sleutels wanneer de bedoelde formulieren via de nieuwe route werken en de terugweg niet meer nodig is.