Was ist Cloudflare Turnstile? Modi, Token und Verifizierung

what is cloudflare turnstile - What Is Cloudflare Turnstile? Modes, Token and Verification

Was ist Cloudflare Turnstile? Cloudflare Turnstile ist eine Captcha-Alternative von Cloudflare: Statt Bilderrätseln prüft sie Besucher mit Tests, die im Hintergrund laufen. Besteht der Besucher, erhält die Seite einen Token, den der Server der Website anschließend bei Cloudflare verifiziert. Dieser Leitfaden behandelt die drei Widget-Modi, den Token und seine Grenzen, die Verifizierung und wie Sie das Widget von der ganzseitigen Challenge unterscheiden.

Was der Besucher sieht: drei Widget-Modi

Cloudflare beschreibt drei Modi in seiner Widget-Dokumentation. Der Betreiber der Website wählt beim Anlegen des Widgets einen davon aus.

ModusWas der Besucher sieht
Managed-ModusCloudflare entscheidet zwischen einer nicht interaktiven Prüfung und einer Checkbox, sodass eine Checkbox nur erscheint, wenn eine weitere Prüfung nötig ist
Non-interactive-ModusEin Widget mit einer Ladeanzeige, während die Prüfungen laufen, und der Besucher muss nie etwas tun
Invisible-ModusGar nichts: kein Widget und keine Ladeanzeige, die Prüfungen laufen im Hintergrund

Keiner der drei Modi verlangt vom Besucher, verzerrten Text zu lesen oder Bilder auszuwählen. Laut der Cloudflare-Übersicht muss eine Website ihren Datenverkehr nicht über Cloudflare leiten, um das Widget zu nutzen, doch ihr Betreiber braucht ein Cloudflare-Konto, um eines anzulegen.

Was liefert Cloudflare Turnstile an die Seite? Einen Token

Für Entwickler läuft es auf ein Formularfeld namens cf-turnstile-response hinaus, auf einen Verifizierungsaufruf am Server und, wenn Sie eine Website automatisieren, die es verwendet, auf einen Token, den Sie selbst liefern müssen. Sitzt das Widget in einem Formular, fügt es laut Cloudflare ein unsichtbares Eingabefeld namens cf-turnstile-response hinzu, das mit den anderen Feldern zum Server wandert. Das Widget lässt sich implizit rendern, dann durchsucht es das Markup nach einem Element mit der Klasse cf-turnstile, oder explizit mit einem Aufruf von turnstile.render() aus dem Skript der Seite. Eine Seite, die explizit rendert, kann auch einen Callback übergeben, und die CapSkip-API-Dokumentation sagt, dass Sie diesen Callback mit dem zurückgegebenen Token ausführen sollen, falls die Seite einen definiert.

Der Token ist kurzlebig. Der Leitfaden zur serverseitigen Validierung nennt für jeden Token eine Gültigkeit von 300 Sekunden und die einmalige Verwendung, und Cloudflare verfolgt die Einlösung in seinem Netzwerk mit Verzögerung. Ein Token, den Sie am Anfang eines langen Skripts anfordern, kann also verbraucht oder veraltet sein, wenn das Formular abgeschickt wird.

So verifiziert der Server den Token

Das bloße Empfangen des Feldes beweist nichts. Cloudflare bezeichnet die serverseitige Validierung als zwingend: Die Website sendet den Token und ihren geheimen Schlüssel an den siteverify-Endpunkt, einen POST an https://challenges.cloudflare.com/turnstile/v0/siteverify, und liest eine JSON-Antwort. Die dokumentierten Werte stehen unten.

RichtungWertBedeutung
Gesendetsecret (erforderlich)Der geheime Schlüssel des Widgets
Gesendetresponse (erforderlich)Der Token aus dem Formularfeld
Gesendetremoteip (optional)Die IP-Adresse des Besuchers
Gesendetidempotency_key (optional)Eine UUID, die Sie erzeugen, damit die Wiederholung derselben Prüfung unbedenklich ist
ZurückgegebensuccessOb die Validierung bestanden wurde
Zurückgegebenchallenge_ts, hostnameWann die Challenge gelöst wurde und wo sie ausgeliefert wurde
Zurückgegebenerror-codesEine Liste wie missing-input-response oder timeout-or-duplicate
Zurückgegebenaction, cdataEigene Werte, die die Seite am Widget gesetzt hat

Cloudflare listet sieben Fehlercodes auf, und zwei sind hier wichtig. Der Code missing-input-response bedeutet, dass kein Token bei Cloudflare angekommen ist, und timeout-or-duplicate bedeutet, dass der Token abgelaufen ist oder bereits validiert wurde. Die dokumentierte Antwort enthält keinen Score: Das Ergebnis lautet bestanden oder nicht bestanden, dazu kommen die Werte action und cdata, die Ihre Seite gesetzt hat, damit der Server sie prüfen kann. Das ist eine Auslegung der dokumentierten Felder und keine Aussage von Cloudflare darüber, was nie zurückgegeben wird.

Widget oder Challenge-Seite: Welches Turnstile ist das?

Das Widget ist eine Sache und die ganzseitige Challenge eine andere. Das Widget ist ein Element in einer Seite, die bereits geladen ist. Eine Challenge-Seite zeigt Cloudflare anstelle der Website, bevor irgendein Inhalt ankommt. Die Clearance-Dokumentation von Cloudflare sagt, dass das Lösen einer solchen Challenge ein Cookie cf_clearance setzt, das an den Besucher und das Gerät gebunden ist. Sie sagt auch, dass ein Widget mit aktivierter Pre-Clearance dieses Cookie ausstellen kann, während das Widget standardmäßig einen einmaligen Token ausstellt. Anhand dieser Tabelle entscheiden Sie, was Sie vor sich haben.

Was Sie sehenWas es istWas CapSkip von Ihnen braucht
Eine Box oder Ladeanzeige in einem Formular und ein Eingabefeld cf-turnstile-response im HTMLDas Widget, im Managed- oder Non-interactive-ModusDen Sitekey und die vollständige Seitenadresse. Der Token kommt ins Feld
Ein Formular, das ohne Token fehlschlägt, aber keine Box auf dem BildschirmDas Widget im Invisible-Modus oder eines, das nicht gerendert wurdeDieselben zwei Werte. Den Sitekey finden Sie im Markup oder im Render-Aufruf
Eine ganze Seite mit dem Text "Just a moment", bevor die Website lädtDie ganzseitige ChallengeZwei CapSkip-Wege: eine Turnstile-Token-Anfrage mit action, data und pagedata, wenn die Seite sie an turnstile.render übergibt, oder die weiter unten beschriebene Anfrage nach dem Cookie cf_clearance

Einen Turnstile-Token von CapSkip holen

CapSkip läuft auf Ihrem eigenen Windows-PC und antwortet auf 127.0.0.1:8080 im Anfrageformat von 2captcha, ohne Gebühr pro Lösung bei einer lizenzierten Kopie. Die Seite Löser für Cloudflare Turnstile stellt das Produkt vor, und die API-Dokumentation listet die hier verwendeten Parameter auf. Läuft Ihr Skript auf einem anderen Rechner, schalten Sie CapSkip in den Server-Modus und verwenden die Adresse dieses PCs als Host, wie es der Abschnitt Verbindungseinstellungen der Einrichtungsanleitung erklärt. CapSkip öffnet seinen Port für jede Adresse, sobald der Server-Modus startet. Um ihn auf die Rechner zu beschränken, die Sie erwarten, fügen Sie eine Blockregel der Windows-Firewall für alle anderen hinzu.

Hier ist die Widget-Anfrage von Hand. Die Methode ist turnstile, und die API-Dokumentation nennt sitekey und pageurl als Pflichtwerte. Jeder Aufruf ist eine Zeile curl.exe, die PowerShell wie geschrieben ausführt. Lassen Sie in cmd die Zeilen weg, die mit einer Raute beginnen.

# 1. Submit the task. CapSkip answers with a task id.
curl.exe -s -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=YOUR_SITEKEY&pageurl=https://example.com/contact&json=1" http://127.0.0.1:8080/in.php
# {"status":1,"request":"12345"}

# 2. Poll with that id until the token is ready.
curl.exe -s "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
# {"status":0,"request":"CAPCHA_NOT_READY"} means poll again shortly.
# {"status":1,"request":"TOKEN","userAgent":"Mozilla/5.0 ..."}

Dieselbe Aufgabe über das Python-SDK ist ein einziger Aufruf. Er sendet, fragt ab und gibt ein Dictionary zurück, dessen Wert code der Token für das Feld cf-turnstile-response ist.

# python -m pip install capskip
from capskip import CapSkip

# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)

result = solver.turnstile("YOUR_SITEKEY", "https://example.com/contact")

print(result["code"])  # the token for the cf-turnstile-response field
print(result.get("userAgent"))  # the User-Agent to send with it

Laut API-Dokumentation löst CapSkip Turnstile mit einem bestimmten Browser-User-Agent, und Sie müssen denselben senden, wenn Sie den Token absenden. Bei der JSON-Antwort steht er als userAgent darin, im Klartextmodus kommt er im Antwort-Header X-Turnstile-User-Agent. Das SDK fordert die JSON-Antwort an, lesen Sie den Wert also aus dem Ergebnis und setzen Sie ihn in die Anfrage, die den Token mitführt.

Die Anfrage für die Challenge-Seite

Für eine Challenge-Seite verlangt die API-Dokumentation drei weitere Werte, die Sie aus den Argumenten lesen, die die Seite an turnstile.render() übergibt. Senden Sie die Werte, die die Seite definiert, und senden Sie keine leeren. Die Dokumentation enthält ein kurzes Skript, das diese Funktion überschreibt und die Argumente ausgibt.

AnfragewertWo die Seite ihn ablegt
actionDas Attribut data-action oder die action im Render-Aufruf
dataDer Wert cData im Render-Aufruf oder das Attribut data-cdata
pagedataDer Wert chlPageData im Render-Aufruf
# python -m pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)

# action, data and pagedata come from the page's turnstile.render call.
result = solver.turnstile(
    "YOUR_SITEKEY",
    "https://example.com/protected",
    action="managed",
    data="YOUR_CDATA",
    pagedata="YOUR_CHLPAGEDATA",
)
print(result["code"], result.get("userAgent"))

Der Wert managed für action stammt aus der Beispielanfrage in der API-Dokumentation. Verwenden Sie also die action, die Ihre Seite definiert.

Die Cookie-Route ist eine andere Anfrage. Die API-Dokumentation führt sie unter Cloudflare Challenge (cf_clearance) auf, für die ganze Seite mit dem Text "Just a moment". Sie funktioniert nur über die JSON-API createTask, ist ausgeschaltet, bis Sie unter den Cloudflare-Einstellungen Return cf_clearance cookies einschalten, und jede Anfrage muss den Proxy nennen, den Sie danach verwenden. Das Python-SDK hat dafür keinen Aufruf, daher steht hier die Anfrage in der Form, in der die API-Dokumentation sie schreibt, gesendet mit PowerShell. Der Wert für proxy ist der Platzhalter aus der Dokumentation.

# Submit the cookie task. A proxy is required.
$body = '{"clientKey":"YOUR_API_KEY","task":{"type":"AntiCloudflareTask","websiteURL":"https://www.example.com/","proxy":"203.0.113.10:8080:login:password"}}'
$task = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/createTask -ContentType "application/json" -Body $body

# Poll every few seconds while the status is processing.
$ask = @{ clientKey = "YOUR_API_KEY"; taskId = $task.taskId } | ConvertTo-Json
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/getTaskResult -ContentType "application/json" -Body $ask
} while ($result.status -eq "processing")

$result.solution.cookies.cf_clearance
$result.solution.userAgent

Verwenden Sie die Cookie-Anfrage, wenn Sie die Website nach der Challenge mit gewöhnlichen HTTP-Anfragen abrufen wollen. Die API-Dokumentation beschreibt diesen Fall für ein Skript oder Tool ohne eigenen Browser und sagt, dass Sie das Cookie über denselben Proxy und mit demselben User-Agent senden sollen. Die Token-Anfrage passt zu einer Seite, die turnstile.render() aufruft und einen Callback oder ein Feld hat, das den Token aufnimmt. Diese Zuordnung für die Token-Anfrage ist ein Schluss aus den beiden Abschnitten der Dokumentation und keine Aussage von ihr.

Zur Wiederverwendung des Cookies in Python siehe wie Sie cf_clearance-Cookies wiederverwenden. Die Token-Anfrage im Code zeigt der Node.js-Leitfaden. Die PHP-Version steht in Turnstile in PHP lösen, und die C#-Version steht in der C#-Anleitung zur Challenge-Seite.

Was ich ausgeführt habe und was es nicht zeigt

Ich habe alle vier Codeblöcke gegen einen Mock ausgeführt, der CapSkip spielt, auf Python 3.11.7, 3.13.7 und 3.14.0 mit capskip 1.7.0, und die beiden PowerShell-Blöcke in Windows PowerShell 5.1. Ich habe keine Aufgabe an die echte App gesendet, daher zeigt nichts hier, wie eine echte Turnstile-Seite antwortet oder was die echte App für ein Widget zurückgibt.

Prüfung gegen den MockErgebnis
Python-Widget-AufrufEine Aufgabe mit der Methode turnstile, dem Sitekey und der Seitenadresse, und im Ergebnis kamen der Token und der User-Agent zurück
Python-Aufruf für die Challenge-SeiteDieselbe Aufgabe enthielt zusätzlich action, data und pagedata, genau wie übergeben
Beide Python-Blöcke in einer Datei zusammengefügtBeide Aufgaben wurden gesendet und zurückgelesen
Cookie-Route in PowerShellDer Mock sah den type AntiCloudflareTask, die Seitenadresse und den Proxy. Er antwortete einmal mit processing, dann mit dem Cookie und dem User-Agent, die der Block ausgab
curl.exe senden, dann abfragenDie erste Abfrage meldete, dass die Aufgabe nicht bereit war, und die zweite lieferte den Token

FAQ

Wie lange gilt ein Turnstile-Token?

Laut Cloudflare 300 Sekunden, und Token sind für die einmalige Verwendung gedacht. Fordern Sie den Token von CapSkip direkt vor dem Absenden des Formulars an.

Ist Turnstile dasselbe wie die Cloudflare-Prüfung, bevor eine Website lädt?

Nein. Das Widget sitzt in einer Seite und liefert einen Token. Die ganzseitige Challenge ersetzt die Seite und endet in einem Cookie cf_clearance. Die Entscheidungstabelle oben zeigt, wie Sie beide unterscheiden.

Kann ich ein Turnstile-Widget ansehen, bevor ich Code schreibe?

Ja. Sehen Sie sich die Turnstile-Demoseite an, um ein Live-Widget und das Feld zu sehen, das es füllt.

Kann ich den Löser von einem anderen PC aus aufrufen?

Ja, über den Server-Modus. Verwenden Sie die Adresse des PCs, auf dem CapSkip läuft, als Host, und fügen Sie eine Blockregel der Windows-Firewall für jede Adresse hinzu, die ihn nicht erreichen soll. Der Löser läuft weiterhin auf Ihrer eigenen Windows-Hardware.

Die Kurzfassung

Kurz gesagt, was ist Cloudflare Turnstile? Ein Token in cf-turnstile-response, den die Website bei Cloudflare prüft, daneben eine eigene ganzseitige Challenge, die in einem Cookie endet. Um den Token oder das Cookie aus Ihrem eigenen Code bereitzustellen, genügt ein lokales Tool zur Captcha-Umgehung wie CapSkip: Es arbeitet auf Ihrem eigenen PC, mit einer Pauschallizenz und ohne Gebühr pro Lösung.