Inhalt des Artikels

Einführung: Was Sie von dieser Anleitung erwarten können

Cloudflare Turnstile ist genau dieses kleine Widget mit dem drehenden Kreis und der Aufschrift „Verifying“, das immer häufiger anstelle der klassischen Bild-Captcha auftaucht. Es steht auf Registrierungsformularen, in Warenkörben von Onlineshops, auf Landingpages und in Kundenkonten von Diensten. Der normale Besucher bemerkt es kaum. Für Marketer, Affiliate-Marketer oder Entwickler, die über mobile Proxys arbeiten und täglich Dutzende Websites öffnen, wird es jedoch zum Rätsel. Warum läuft die Prüfung bei einem Profil in einer Sekunde durch, während das Widget bei einem anderen zögert, ein Häkchen verlangt oder einen Fehlercode ausgibt?

In dieser Anleitung betrachten wir Cloudflare Turnstile von zwei Seiten. Aus Sicht des Website-Betreibers – Sie binden das Widget eigenhändig auf Ihrer Seite ein, richten die serverseitige Prüfung ein und lernen, die Statistiken zu lesen. Aus Sicht des Besuchers – Sie verstehen, welche Signale Turnstile sammelt, was es über Ihren Browser, Ihr Netzwerk und Ihren Proxy sieht und warum es welche Entscheidung trifft. Dieses Wissen ist gleichermaßen nützlich für diejenigen, die ihre Formulare vor Bots schützen, und für diejenigen, die wollen, dass ihre Arbeitsprofile bei der Prüfung wie normale Nutzer wirken.

Für wen diese Anleitung gedacht ist

  • Für Geschäftsinhaber und Marketer, bei denen Spam-Anfragen und Fake-Registrierungen die Statistik verfälschen und das Budget auffressen.
  • Für Entwickler, die Turnstile schnell und fehlerfrei in ein Formular einbauen und das Token serverseitig korrekt prüfen müssen.
  • Für Affiliate-Marketer und Multi-Accounting-Spezialisten, die über mobile Proxys arbeiten und verstehen wollen, was Turnstile bei ihrer Verbindung sieht.

Was Sie vorher wissen sollten

Spezielle Vorkenntnisse sind nicht nötig. Es reicht, wenn Sie verstehen, was eine HTML-Seite ist, die Entwicklerkonsole im Browser öffnen können und zumindest minimale Erfahrung mit einer serverseitigen Sprache haben – PHP, Node.js, Python. Wenn Sie keinen Server haben, durchlaufen Sie trotzdem den Großteil der Anleitung: Das Widget lässt sich auch auf einer lokalen Seite einbinden und testen.

Wie viel Zeit Sie benötigen

Die vollständige Durcharbeitung dauert etwa eineinhalb bis zwei Stunden. Registrierung und Erstellung des Widgets dauern 10–15 Minuten, das Einbetten in die Seite 20 Minuten, die serverseitige Prüfung 30–40 Minuten, Testen und Diagnose nochmals 30 Minuten. Die theoretischen Abschnitte können Sie in beliebiger Reihenfolge lesen und bei Bedarf zurückkehren.

Vorbereitung: Werkzeuge und Zugänge

Bevor Sie beginnen, sammeln Sie alles Notwendige. Das erspart Ihnen Pausen mitten im Prozess.

Benötigte Werkzeuge und Zugänge

  • Cloudflare-Konto. Kostenlos. In ein paar Minuten per E-Mail registriert. Eine Domain muss nicht zu Cloudflare übertragen werden – Turnstile funktioniert auf jeder Website, egal wo sie gehostet ist.
  • Website oder Testseite. Jede HTML-Seite mit einem Formular ist geeignet. Für lokale Experimente genügt eine Datei auf dem Computer, die über einen einfachen lokalen Server geöffnet wird.
  • Serverumgebung. Beliebiger Hosting mit PHP oder Node.js bzw. Python auf Ihrem Rechner. Wird für die zweite Hälfte der Anleitung benötigt – die Prüfung des Tokens.
  • Moderner Browser. Chrome, Firefox, Edge oder Safari in aktueller Version mit geöffneten Entwicklerwerkzeugen.
  • Mobiler Proxy mit der Möglichkeit, die IP zu wechseln. Wird im Diagnoseabschnitt benötigt, um zu sehen, wie das Widget auf verschiedene Netzwerke und Adressrotation reagiert.

Systemanforderungen

Turnstile ist anspruchslos. Das Widget läuft in jedem Browser, der modernes JavaScript unterstützt, und lädt seinen Code von der Domain challenges.cloudflare.com. Wenn diese Domain in Ihrem Netzwerk oder durch Browser-Erweiterungen blockiert wird, lädt das Widget nicht – berücksichtigen Sie das beim Testen. Für die serverseitige Prüfung benötigen Sie die Möglichkeit, ausgehende HTTPS-Anfragen zu stellen.

Was Sie vor dem Start vorbereiten sollten

  1. Legen Sie eine Textdatei für Notizen an. Darin notieren Sie den Site Key, den Namen des Widgets, die Liste der Hostnamen und die Testergebnisse.
  2. Öffnen Sie die Seite mit dem Formular, das Sie schützen möchten, und speichern Sie eine Kopie mit Datumsvermerk. Das ist Ihr Backup.
  3. Wenn Sie einen serverseitigen Formular-Handler haben, machen Sie auch davon eine Kopie. Wir werden Prüfcode hinzufügen.
  4. Prüfen Sie, dass Ihr lokaler oder Produktivserver die Seite über HTTPS oder über localhost ausliefert. Turnstile funktioniert auch über normales HTTP, aber auf der Produktivseite brauchen Sie ohnehin HTTPS.

⚠️ Achtung: Der geheime Schlüssel des Widgets darf nicht im HTML, im JavaScript auf der Seite oder in einem öffentlichen Repository gespeichert werden. Er lebt ausschließlich auf dem Server. Wenn Sie ihn versehentlich veröffentlicht haben, geben Sie den Schlüssel sofort im Cloudflare-Panel neu aus – der alte wird ungültig.

Grundbegriffe: Wie Cloudflare Turnstile aufgebaut ist

Damit die weiteren Schritte verständlich sind, klären wir die Schlüsselbegriffe in einfacher Sprache.

Schlüsselbegriffe

  • Widget – der Block, den der Besucher sieht. Technisch ist es ein iframe, der von der Cloudflare-Domain geladen und in Ihre Seite eingebettet wird.
  • Site Key – die öffentliche Kennung des Widgets. Sie wird ins HTML eingefügt und ist für alle sichtbar. Anhand ihrer erkennt Cloudflare, welches Widget gerendert werden soll und für welche Domains es erlaubt ist.
  • Secret Key – der private Schlüssel. Mit ihm bestätigt Ihr Server, dass das eingegangene Token echt ist. Er verlässt niemals den Server.
  • Token – die Zeichenkette, die das Widget nach erfolgreicher Prüfung ausgibt. Sie wird in ein verstecktes Formularfeld gelegt und geht zusammen mit den übrigen Daten an Ihren Server.
  • Siteverify – der Cloudflare-Endpunkt, an den der Server das Token zusammen mit dem geheimen Schlüssel sendet und eine Antwort erhält: Erfolg oder nicht.
  • Widget-Modus – die Art der Anzeige: Managed, Non-interactive oder Invisible. Der Unterschied wird unten beschrieben.
  • Hostname – die Domain, auf der das Widget verwendet werden darf. Ist die Domain nicht angegeben, verweigert das Widget mit einem Fehler die Arbeit.

Das Prinzip in vier Sätzen

  1. Die Seite lädt das Turnstile-Skript, und das Widget startet still eine Reihe von Prüfungen im Browser.
  2. Cloudflare sammelt die Ergebnisse, bewertet sie zusammen mit den Netzwerkdaten und entscheidet: sofort durchlassen, ein Häkchen zur Bestätigung zeigen oder ablehnen.
  3. Bei Erfolg erzeugt das Widget ein Einmal-Token und fügt es ins Formular ein.
  4. Ihr Server erhält das Formular, sendet das Token an siteverify und verarbeitet die Anfrage nur bei positiver Antwort.

Was Turnstile prüft – das Gesamtbild

Hier ist das Wichtigste zu verstehen. Cloudflare Turnstile prüft „Menschlichkeit“ nicht über Bilderrätsel. Es bewertet die Konsistenz der Umgebung: wie sehr Browser, Netzwerk und Verhalten zu einem stimmigen Bild passen. Die wichtigsten Signal gruppen:

  • Browser-Umgebung. Das Skript führt eine Reihe kleiner JavaScript-Aufgaben aus und prüft, dass sich die Umgebung wie ein echter Browser verhält: wie die Objekte des Fensters aufgebaut sind, wie Grafik gerendert wird, ob es Anzeichen für Automatisierung gibt und ob der angegebene User-Agent zu den tatsächlichen Fähigkeiten der Engine passt.
  • Proof of Work. Das Widget bittet den Browser, eine kleine Berechnung durchzuführen. Für einen Menschen sind das Sekundenbruchteile, für einen Bot, der Tausende Seiten öffnet, eine spürbare Last.
  • Netzwerksignale. Reputation der IP-Adresse und des autonomen Systems, aus dem die Anfrage kommt, Übereinstimmung der Netzwerkmerkmale mit dem angegebenen Browser, die Historie der Anfragen von dieser Adresse im gesamten Cloudflare-Netzwerk.
  • Vertrauens-Token des Geräts. Auf Apple-Geräten und in einigen anderen Ökosystemen kann Turnstile vom Betriebssystem die Bestätigung anfordern, dass es sich um ein echtes Gerät handelt – dann läuft die Prüfung ganz ohne Berechnung durch.
  • Verhalten auf der Seite. Zeitpunkt des Erscheinens des Widgets, Moment des Absendens des Formulars, Natürlichkeit der Aktionen im Managed-Modus.

Was Turnstile nicht tut: Es sammelt keine Daten für Werbeprofilierung, verfolgt den Nutzer nicht über Websites hinweg über Drittanbieter-Cookies und zeigt niemals Bild-Puzzles. Das ist wichtig sowohl im Hinblick auf das Datenschutzrecht als auch auf die Conversion – Besucher springen nicht wegen einer nervigen Captcha ab.

Die drei Widget-Modi

  • Managed – der Standardmodus. Das Widget ist sichtbar, dreht den Indikator und zeigt bei Zweifeln ein Häkchen, das angeklickt werden muss. Geeignet für die meisten Formulare.
  • Non-interactive – das Widget ist sichtbar, verlangt aber niemals eine Aktion. Entweder läuft es von selbst durch oder es gibt einen Fehler aus. Gut für Seiten, auf denen zusätzliche Klicks nicht vorkommen dürfen.
  • Invisible – das Widget wird überhaupt nicht gerendert. Die Prüfung läuft im Hintergrund. Praktisch für Buttons und Formulare, deren Design Sie nicht ändern möchten, erfordert aber eine sorgfältige Fehlerbehandlung.

Schritt 1: Verstehen, was Turnstile auf Ihrer Seite sieht

Ziel dieses Abschnitts: Bevor Sie etwas konfigurieren, müssen Sie verstehen, welche Daten über Ihre Umgebung das Widget erhält. Das ist die Grundlage für die Diagnose in den folgenden Schritten und für die bewusste Arbeit über mobile Proxys.

So beobachten Sie die Arbeit des Widgets mit eigenen Augen

  1. Öffnen Sie eine beliebige Website, auf der Cloudflare Turnstile läuft. Solche Widgets erkennt man leicht am Cloudflare-Logo in der rechten unteren Ecke des Blocks und an den Links „Privacy“ und „Terms“.
  2. Drücken Sie F12 oder klicken Sie mit der rechten Maustaste – „Untersuchen“, um die Entwicklerwerkzeuge zu öffnen.
  3. Wechseln Sie zum Tab „Network“ (Netzwerk) und laden Sie die Seite neu.
  4. Geben Sie im Filterfeld challenges.cloudflare.com ein. Sie sehen mehrere Anfragen: das Laden von api.js, das Laden des Widget-iframes selbst und eine oder mehrere POST-Anfragen – das ist die Übermittlung der Prüfergebnisse.
  5. Öffnen Sie den Tab „Elements“ (Elemente) und suchen Sie den Block mit der Klasse cf-turnstile. Darin erscheint nach erfolgreicher Prüfung ein verstecktes Feld input mit dem Namen cf-turnstile-response und einer langen Zeichenkette als Wert. Das ist das Token.

Tipp: Der Inhalt der POST-Anfragen ist verschlüsselt und obfuskiert, das Lesen ist zwecklos. Achten Sie auf etwas anderes: wie viele Anfragen gesendet wurden, wie lange die Prüfung dauerte und ob der Status des Widgets auf „Success“ gewechselt hat. Das ist Ihr externer Vertrauensindikator.

Was Turnstile über Ihren Browser sieht

Das Widget führt JavaScript direkt in Ihrem Fenster aus und hat daher Zugriff auf alles, worauf auch jedes andere Skript auf der Seite Zugriff hat: Version der Engine, installierte APIs, Bildschirmgrößen, Zeitzone, Interface-Sprachen, Besonderheiten beim Rendern von Grafik und Schriften, Verhalten von Funktionen, die in automatisierten Browsern oft überschrieben sind. Es liest keine Dateien und greift nicht auf andere Tabs zu. Aber es bemerkt sehr wohl, wenn ein Browser das eine behauptet und das andere tut. Zum Beispiel sagt der User-Agent „Chrome auf Android“, aber in der Umgebung fehlen Touch-Events und es gibt APIs, die es auf Mobilgeräten nicht gibt.

Was Turnstile über Ihr Netzwerk sieht

Hier wird es für diejenigen interessant, die über mobile Proxys arbeiten. Alle Anfragen des Widgets gehen an die Server von Cloudflare, das heißt, Cloudflare sieht Ihre externe IP-Adresse, deren autonomes System (also den Betreiber), das Land sowie die tieferen Eigenschaften der Verbindung – wie genau Ihr Client die gesicherte Verbindung aufbaut. Diese Eigenschaften unterscheiden sich je nach Browser, und Cloudflare vergleicht sie mit dem angegebenen User-Agent.

Mobilfunkbetreiber vergeben Adressen aus großen gemeinsamen Pools; hinter einer Adresse sitzen gleichzeitig Hunderte echter Teilnehmer. Daher haben solche Adressen von Natur aus eine neutrale oder gute Reputation – sie zu blockieren würde bedeuten, echte Menschen zu blockieren. Aber die Reputation ist nur eines der Signale. Wenn von einer mobilen Adresse ein Browser kommt, dessen Netzwerk-Fingerprint zu einem Desktop-Skript gehört, dessen Zeitzone auf einem anderen Kontinent liegt und der Anzeichen von Automatisierung zeigt, passt das Bild nicht mehr zusammen, und das Widget schaltet in den interaktiven Modus um oder verweigert.

Was Turnstile über Ihr Verhalten sieht

Im Managed-Modus achtet das Widget darauf, wie schnell das Formular nach dem Laden abgesendet wird, ob der Nutzer mit der Seite interagiert hat und wie natürlich der Klick auf das Häkchen wirkt. Im Invisible- und Non-interactive-Modus ist die Verhaltenskomponente minimal – die Entscheidung wird anhand von Umgebung und Netzwerk getroffen.

✅ Prüfung: In diesem Schritt sollten Sie in der Lage sein, den Tab Network zu öffnen, Anfragen an challenges.cloudflare.com zu filtern, das versteckte Feld cf-turnstile-response zu sehen und mit eigenen Worten die drei Signal gruppen zu erklären: Browser, Netzwerk, Verhalten. Wenn das geklappt hat – gehen Sie zur Erstellung Ihres eigenen Widgets über.

Mögliche Probleme

  • Es gibt überhaupt keine Anfragen an challenges.cloudflare.com. Wahrscheinlich wird die Domain durch eine Browser-Erweiterung oder einen Unternehmensfilter blockiert. Deaktivieren Sie für die Tests die Blocker.
  • Das Widget hängt endlos im Prüfzustand. Prüfen Sie die Systemzeit des Computers: eine starke Abweichung von der realen Zeit bricht die Prüfung.

Schritt 2: Ein Widget im Cloudflare-Panel erstellen

Ziel dieses Abschnitts: ein Schlüsselpaar erhalten – Site Key und Secret Key – und die Liste der Domains sowie den Arbeitsmodus richtig einstellen.

  1. Öffnen Sie das Cloudflare-Verwaltungspanel und melden Sie sich an. Falls Sie kein Konto haben – klicken Sie auf „Sign up“, geben Sie E-Mail und Passwort ein, bestätigen Sie die E-Mail.
  2. Suchen Sie im linken Menü den Punkt Turnstile. Wenn Sie mehrere Konten haben, wählen Sie zuerst auf der Startseite das richtige aus.
  3. Klicken Sie auf die blaue Schaltfläche Add widget (Widget hinzufügen).
  4. Geben Sie im Feld Widget name einen aussagekräftigen Namen ein, zum Beispiel „Landingpage Anfragen – Haupt“. Der Name ist nur für Sie sichtbar, aber bei einem Dutzend Widgets erspart er Verwirrung.
  5. Klicken Sie im Block Hostname management auf Add hostnames und geben Sie die Domains ein, auf denen das Widget laufen soll. Ohne Protokoll und ohne Pfad: example.ru, nicht https://example.ru/form. Subdomains müssen separat hinzugefügt werden, oder Sie geben die Root-Domain an – dann sind auch Subdomains erlaubt.
  6. Fügen Sie für lokale Tests localhost zur Liste hinzu. Das ist offiziell unterstützt und stört den Produktivbetrieb nicht.
  7. Wählen Sie im Block Widget Mode den Modus. Nehmen Sie für das erste Mal Managed – so sehen Sie alle Zustände des Widgets, einschließlich des interaktiven.
  8. Lassen Sie die Option Pre-clearance zunächst ausgeschaltet. Sie ist nur nötig, wenn die Website über Cloudflare proxied wird, und darüber sprechen wir im fortgeschrittenen Abschnitt.
  9. Klicken Sie auf Create.
  10. Auf dem nächsten Bildschirm sehen Sie zwei Felder: Site Key und Secret Key. Kopieren Sie beide in Ihre Notizdatei. Der geheime Schlüssel lässt sich später in den Widget-Einstellungen einsehen, aber es ist bequemer, ihn gleich zu speichern.

Tipp: Erstellen Sie gleich zwei Widgets – eines für die Produktivdomain, ein zweites mit dem Namen „Test“ und dem Hostnamen localhost. So experimentieren Sie mit Modi und Einstellungen, ohne die Statistik des Arbeits-Widgets zu berühren.

Wie das richtige Ergebnis aussieht

In der Turnstile-Liste erscheint eine Karte mit dem Namen des Widgets, seinem Modus und der Liste der Hostnamen. Der Site Key beginnt mit „0x“ und ist etwa 24 Zeichen lang, der Secret Key ebenfalls mit „0x“, aber länger. Wenn der Schlüssel anders aussieht, haben Sie höchstwahrscheinlich das falsche Feld kopiert.

✅ Prüfung: In Ihrer Notizdatei sind Site Key, Secret Key, Widget-Name, Hostnamen-Liste und gewählter Modus festgehalten. Im Cloudflare-Panel wird das Widget in der Liste mit dem Status „aktiv“ angezeigt.

Mögliche Probleme

  • Die Schaltfläche Create ist inaktiv. Es wurde kein Hostname hinzugefügt oder einer mit Fehler eingegeben (Protokoll, Schrägstrich, Leerzeichen).
  • Der Punkt Turnstile ist im Menü nicht zu finden. Sie befinden sich in den Einstellungen einer bestimmten Domain. Gehen Sie auf die Kontoebene zurück – Turnstile lebt dort, nicht innerhalb der Zone.

Schritt 3: Das Widget in die Seite mit dem Formular einbinden

Ziel dieses Abschnitts: Das Widget erscheint auf Ihrer Seite, besteht die Prüfung und fügt das Token in das Formular ein.

Das Skript einbinden

  1. Öffnen Sie die HTML-Datei der Seite mit dem Formular im Editor.
  2. Fügen Sie innerhalb des head-Tags oder vor dem schließenden body-Tag die Zeile zur Skript-Einbindung ein:
<script src='https://challenges.cloudflare.com/turnstile/v0/api.js' async defer></script>

Die Attribute async und defer sorgen dafür, dass die Seite nicht auf das Laden des Skripts wartet. Das Widget erscheint etwas später, aber der Nutzer bemerkt keine Verzögerung beim Laden der Inhalte.

Den Widget-Container platzieren

  1. Suchen Sie das Formular, das Sie schützen. In der Regel ist es ein form-Tag mit Feldern für Name, E-Mail, Telefon.
  2. Fügen Sie direkt vor der Absende-Schaltfläche einen leeren Block mit der Klasse cf-turnstile und Ihrem Site Key ein:
<form action='/submit.php' method='POST'> <input type='text' name='name' placeholder='Ihr Name'> <input type='email' name='email' placeholder='E-Mail'> <div class='cf-turnstile' data-sitekey='IHR_SITE_KEY' data-theme='light'></div> <button type='submit'>Senden</button> </form>
  1. Ersetzen Sie IHR_SITE_KEY durch den Schlüssel aus Ihrer Notizdatei. Den geheimen Schlüssel dürfen Sie hier nicht einfügen.
  2. Speichern Sie die Datei und öffnen Sie die Seite im Browser über localhost.

Was Sie sehen sollten

Ein bis zwei Sekunden nach dem Laden erscheint an der Stelle des Blocks ein Widget von etwa 300 auf 65 Pixel. Zunächst zeigt es einen Ladeindikator und den Text „Verifying“, dann – ein grünes Häkchen und „Success“. Wenn Cloudflare beschlossen hat, die Umgebung erneut zu prüfen, erscheint eine Checkbox mit dem Text „Verify you are human“ – klicken Sie darauf, und im nächsten Moment zeigt das Widget Erfolg.

Öffnen Sie die Entwicklerwerkzeuge, den Tab Elements, und klappen Sie den Block cf-turnstile auf. Darin ist ein verstecktes Feld input mit dem Namen cf-turnstile-response erschienen. Sein Wert ist ein langes Token. Genau dieses geht beim Absenden des Formulars an den Server.

Nützliche Attribute des Containers

  • data-theme – light, dark oder auto. Auto passt sich dem Systemthema des Nutzers an.
  • data-size – normal, compact oder flexible. Flexible streckt das Widget über die Breite des Containers – praktisch für mobile Layouts.
  • data-language – Sprachcode, zum Beispiel de. Standardmäßig verwendet das Widget die Browsersprache.
  • data-action – kurze Bezeichnung, zum Beispiel login oder checkout. Sie kommt in der siteverify-Antwort zurück und hilft, Formulare in der Statistik zu unterscheiden.
  • data-callback – Name einer JavaScript-Funktion, die nach Erfolg aufgerufen wird. In sie kommt das Token.
  • data-error-callback – Funktion, die den Fehlercode erhält, wenn etwas schiefgelaufen ist.
  • data-refresh-expired – was zu tun ist, wenn das Token abgelaufen ist: auto fordert selbst neu an, manual zeigt einen Aktualisieren-Button, never tut nichts.

Tipp: Fügen Sie gleich data-error-callback hinzu und geben Sie den Fehlercode in der Konsole aus. Die Turnstile-Codes sind informativ: die Serie 110xxx weist auf Probleme mit Schlüssel oder Domain hin, 300xxx auf einen Ausführungsfehler im Browser, 600xxx darauf, dass die Prüfung nicht bestanden wurde. Ohne das werden Sie raten, warum das Widget schweigt.

Alternativer Weg: explizites Rendern über JavaScript

Wenn Sie in einem Framework arbeiten oder den Zeitpunkt des Erscheinens des Widgets steuern möchten, ersetzen Sie das implizite Rendern durch explizites. Fügen Sie der Skript-Adresse den Parameter render=explicit hinzu und rufen Sie turnstile.render mit den gewünschten Parametern auf:

turnstile.render('#my-widget', { sitekey: 'IHR_SITE_KEY', theme: 'auto', action: 'signup', callback: function(token) { console.log('Token erhalten', token.length); } });

Diese Methode erlaubt es, das Widget nach einem Fehler mit der Methode turnstile.reset neu zu zeichnen und das aktuelle Token mit turnstile.getResponse abzurufen.

✅ Prüfung: Das Widget wird auf der Seite angezeigt, zeigt „Success“, im DOM ist das Feld cf-turnstile-response mit Token vorhanden, in der Konsole gibt es keine Fehler. Versuchen Sie, die Seite drei- bis viermal neu zu laden – jedes Mal sollte ein neues Token erscheinen.

Mögliche Probleme

  • Das Widget zeigt Fehler 110200. Die Domain, von der die Seite geöffnet wird, ist nicht in den Hostnamen des Widgets enthalten. Prüfen Sie, dass Sie genau über localhost öffnen und nicht über 127.0.0.1 oder file:// – das sind unterschiedliche Hostnamen.
  • Das Widget erscheint nicht, die Konsole ist leer. Das Skript wurde nicht geladen. Prüfen Sie die Skript-Adresse auf Tippfehler und ob Blocker aktiv sind.
  • Das Widget bricht das Layout. Verwenden Sie data-size='flexible' oder wickeln Sie den Block in einen Container der gewünschten Breite.

Schritt 4: Die serverseitige Prüfung des Tokens einrichten

Ziel dieses Abschnitts: Der Server lehnt alle Formularübermittlungen ohne gültiges Token ab. Das ist der wichtigste Schritt – ohne ihn bleibt das Widget reine Dekoration, weil ein Bot eine POST-Anfrage direkt senden kann, unter Umgehung der Seite.

Wie die Anfrage an siteverify aufgebaut ist

Ihr Server sendet eine POST-Anfrage an https://challenges.cloudflare.com/turnstile/v0/siteverify mit den Feldern:

  • secret – Ihr geheimer Schlüssel;
  • response – das Token aus dem Feld cf-turnstile-response;
  • remoteip – die IP des Besuchers, optional, aber nützlich;
  • idempotency_key – optionaler eindeutiger Bezeichner der Anfrage, darüber im fortgeschrittenen Abschnitt.

Als Antwort kommt JSON. Die wichtigsten Felder:

{ "success": true, "challenge_ts": "2026-03-14T10:22:31.000Z", "hostname": "example.ru", "error-codes": [], "action": "signup", "cdata": "" }

Das Token lebt 300 Sekunden und ist einmalig. Eine erneute Prüfung desselben Tokens liefert den Fehler timeout-or-duplicate.

Beispiel in PHP

  1. Öffnen Sie die Handler-Datei des Formulars, zum Beispiel submit.php.
  2. Fügen Sie ganz am Anfang, vor jeglicher Arbeit mit den Formulardaten, den Prüfblock ein:
<?php $token = $_POST['cf-turnstile-response'] ?? ''; if ($token === '') { http_response_code(400); exit('Prüfung nicht bestanden: kein Token'); } $data = [ 'secret' => getenv('TURNSTILE_SECRET'), 'response' => $token, 'remoteip' => $_SERVER['REMOTE_ADDR'] ]; $ch = curl_init('https://challenges.cloudflare.com/turnstile/v0/siteverify'); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $raw = curl_exec($ch); curl_close($ch); $result = json_decode($raw, true); if (empty($result['success'])) { http_response_code(403); exit('Prüfung nicht bestanden: ' . implode(',', $result['error-codes'] ?? ['no-response'])); } 












Über den Autor







Roman Melnikov












Roman Melnikov


Technical Writer and System Administrator














Berufserfahrung:
Technical writer and DevOps engineer with 9 years of experience. Created over 50 detailed guides on system configuration and administration. His instructions helped thousands of professionals successfully solve technical tasks. Popular author on Habr and YouTube.













Ausbildung:

Bauman Moscow State Technical University. Information Systems and Technologies














Expertise:


Technical Documentation
DevOps
System Administration
Linux
Docker and Kubernetes
CI/CD
Infrastructure Automation
Cloud Technologies
System Monitoring
Bash and Python Scripting























Diesen Artikel teilen: