Was ist hCaptcha? Token, Siteverify und Enterprise erklärt

hCaptcha ist eine Bot-Prüfung, die Sie vor ein Formular setzen. Der Besucher besteht eine Challenge in einem Widget, und das Widget fügt dem Formular dann einen Token namens h-captcha-response hinzu. Ihr Server sendet diesen Token an hCaptcha, um zu bestätigen, dass er echt ist. Was ist hCaptcha also für Entwickler? Ein Widget, ein Token und ein Verifizierungsaufruf, und genau damit haben Sie zu tun, wenn ein Skript eine solche Prüfung bestehen muss. Dieser Leitfaden behandelt, wie Sie hCaptcha erkennen, was der Server prüft, was jeder Fehler bedeutet und was ein Skript sendet.
Die allgemeine Idee eines Captchas finden Sie unter Was ein Captcha ist und warum Websites eines einsetzen. Diese Seite bleibt bei hCaptcha.
So erkennen Sie hCaptcha auf einer Seite
Der hCaptcha-Entwicklerleitfaden zeigt das Widget als Element der Klasse h-captcha, das ein Attribut data-sitekey trägt. Die CapSkip-Seite zu hCaptcha nennt den Sitekey eine öffentliche UUID. Baut ein Skript das Widget stattdessen selbst, ist der Sitekey ein Parameter von hcaptcha.render(), den der Konfigurationsleitfaden dokumentiert. Nach einer erfolgreichen Challenge fügt hCaptcha laut Leitfaden dem Absenden des Formulars den h-captcha-response Token hinzu.
Drei Dinge identifizieren es also: ein Element mit der Klasse h-captcha, ein Sitekey und, sobald die Challenge bestanden ist, ein Formularfeld namens h-captcha-response. Die CapSkip-API-Dokumentation ergänzt, dass ein Formular ein zweites Feld namens g-recaptcha-response tragen kann, das mit demselben Token zu füllen ist.
Checkbox, Invisible und Enterprise-Konten
Checkbox und Invisible sind zwei Widget-Modi. Enterprise ist eine Kontostufe, die beide nutzen kann und die ändert, was die Verifizierungsantwort des Servers enthält. CapSkip verwendet für alle dieselbe Methode.
- Checkbox. Der Besucher setzt ein Häkchen und beantwortet laut CapSkip-Dokumentation manchmal eine Bildaufgabe.
- Invisible. Laut dem Invisible-Leitfaden setzen Sie data-size am Element auf invisible, und das Widget rendert dann im Hintergrund und zeigt sich nur, wenn eine Challenge nötig ist. Ihre Seite löst es mit hcaptcha.execute() aus, und der Token geht an Ihre Callback-Funktion.
- Enterprise. Die Verifizierungsantwort bekommt zwei weitere Felder, score und score_reason, die der hCaptcha-Leitfaden als nur für Enterprise kennzeichnet. CapSkip hat keine Score-Option für eine Aufgabe. Der einzige verwandte Schalter ist High score mode für hCaptcha, behandelt in den FAQ unten.
Manche Enterprise-Websites übergeben dem Widget vor dem Start über hcaptcha.setData() auch einen Wert namens rqdata. Die öffentliche hCaptcha-Dokumentation beschreibt ihn nicht, daher stützt sich alles hier dazu auf die CapSkip-Dokumentation: Die Website gibt pro Challenge einen Wert aus, er veraltet schnell, und ein Skript braucht deshalb für jede Aufgabe einen neuen.
Was der Server mit dem Token macht
Der Server sendet den Token per POST an https://api.hcaptcha.com/siteverify als URL-kodierten Formular-Body, und der Leitfaden warnt davor, JSON zu senden. Zwei Felder sind Pflicht: das geheime Konto-Secret und der Token, gesendet als secret und response. Der Leitfaden empfiehlt remoteip (die Adresse des Nutzers) und nennt sitekey als optional, eine Möglichkeit anzugeben, welchen Sitekey Sie erwarten. Die JSON-Antwort enthält success, challenge_ts, hostname und error-codes.
Token sind nur einmal verwendbar. Die einzige Lebensdauer, die der Leitfaden nennt, ist ein Standard von 120 Sekunden, in der Beschreibung eines Fehlercodes. Die CapSkip-Dokumentation gibt etwa zwei Minuten an. Fordern Sie den Token direkt vor dem Absenden an.
Siteverify-Fehler und was zu prüfen ist
Diese Codes stammen aus der Fehlertabelle im hCaptcha-Leitfaden. Ein Skript sieht meist nur ein abgelehntes Formular. Die letzte Spalte ist eine Einschätzung, was zu prüfen ist, kein Text von hCaptcha.
| Fehlercode | Was der Leitfaden sagt | Was zu prüfen ist |
|---|---|---|
missing-input-response | Der Token-Parameter fehlt. | Der Formular-POST enthielt kein Feld h-captcha-response, oder die Website liest einen anderen Namen. |
invalid-input-response | Der Token ist ungültig oder fehlerhaft aufgebaut. | Der Wert wurde auf dem Weg ins Formular abgeschnitten, verändert oder doppelt kodiert. |
expired-input-response | Der Token ist abgelaufen (Standard 120 s). | Zwischen Lösen und Absenden verging zu viel Zeit. Lösen Sie, dann senden Sie sofort ab. |
already-seen-response | Der Token wurde bereits einmal verifiziert. | Ein Token wurde wiederverwendet, oder ein Formular-POST wurde mit dem alten Token wiederholt. Fordern Sie jedes Mal einen neuen an. |
sitekey-secret-mismatch | Der Sitekey ist mit dem angegebenen Secret nicht registriert. | Ein Konfigurationsproblem auf der Serverseite, nichts, was das Skript sendet. |
invalid-input-secret | Der geheime Schlüssel ist ungültig oder fehlerhaft aufgebaut. | Ebenfalls serverseitig, im Code des Website-Betreibers. |
Wie es sich zu reCAPTCHA und Turnstile verhält
Alle drei legen einen Token ins Formular und verifizieren ihn serverseitig, die Unterschiede liegen also bei Namen und Zahlen. reCAPTCHA verwendet g-recaptcha-response, und laut dem Verifizierungsleitfaden von Google ist ein Token zwei Minuten gültig und lässt sich einmal verifizieren. Turnstile verwendet cf-turnstile-response, und laut dem Leitfaden zur serverseitigen Validierung von Cloudflare gelten 300 Sekunden und die einmalige Verwendung. Im CapSkip-Python-SDK heißen die Aufrufe hcaptcha(), recaptcha() und turnstile(), entnommen aus dem Quellcode von Version 1.7.0.
Wie eine Anfrage an CapSkip aussieht
CapSkip läuft auf Ihrem Windows-PC und spricht das Anfrageformat von 2captcha, eine hCaptcha-Aufgabe sind also zwei HTTP-Aufrufe. Beide curl.exe-Befehle unten laufen wie geschrieben in PowerShell und in cmd. Der erste sendet die Aufgabe und antwortet mit einer Job-ID. Der zweite fragt mit dieser ID ab, und CAPCHA_NOT_READY bedeutet, dass Sie ein paar Sekunden warten und erneut fragen. Fügen Sie das Feld data nur hinzu, wenn die Seite ein rqdata setzt. Der Schlüssel spielt nur eine Rolle, wenn in CapSkip API Key Validation eingeschaltet ist.
curl.exe -X POST -d "key=YOUR_API_KEY&method=hcaptcha&sitekey=YOUR_SITEKEY&pageurl=https://example.com/login&json=1" http://127.0.0.1:8080/in.php curl.exe "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
Dieselbe Aufgabe über das Python-SDK ist ein einziger Aufruf, der sendet, abfragt und das Ergebnis zurückgibt. Die Optionen sind invisible, data (das rqdata von Enterprise), userAgent und proxy. CapSkip verwendet einen userAgent, den Sie senden, nur dann, wenn er zum Browser passt, mit dem es löst. Das Ergebnis enthält den Token als code und token, einen respKey und den User-Agent, der den Token erzeugt hat.
# pip install capskip
from capskip import CapSkip
# The key matters only when API Key Validation is on in CapSkip.
solver = CapSkip(apiKey="YOUR_API_KEY", host="127.0.0.1", port=8080)
# For an Enterprise rqdata add data=RQDATA; for an invisible widget
# add invisible=1. Neither is needed for a plain checkbox.
result = solver.hcaptcha(
sitekey="YOUR_SITEKEY",
url="https://example.com/login",
)
# The token goes in h-captcha-response, sent with this User-Agent.
print(result["code"][:12], result["userAgent"])Beide Blöcke liefen gegen einen Mock von CapSkip und nicht gegen die echte App, und beide sendeten method=hcaptcha mit dem angegebenen Sitekey und der Seitenadresse. Es fand kein echtes Lösen statt, daher gibt es hier keine Aussage zu Lösezeit oder Erfolgsquote. Vollständige Skripte und jeden Parameter finden Sie auf der Seite CapSkip-Löser für hCaptcha, und die Methode steht in der CapSkip-API-Dokumentation.
- hCaptcha in Python mit dem capskip-SDK
- hCaptcha Enterprise in Node.js mit einem frischen rqdata
- hCaptcha in C# mit HCaptchaAsync
CapSkip auf einem Server betreiben
Läuft Ihr Skript auf einem anderen Rechner, schalten Sie CapSkip in den Server-Modus und richten die Host-Einstellung auf diesen Rechner. Die Verbindungseinstellungen in der Einrichtungsanleitung erklären beide Modi, und der Server-Modus verlangt, dass CapSkip als Administrator läuft, und der Rechner bleibt ein Windows-PC unter Ihrer Kontrolle. Prüfen Sie, welche Adressen den Port erreichen können, und fügen Sie eine Blockregel der Windows-Firewall für die hinzu, die es nicht sollen. Weil das Lösen auf diesem Rechner stattfindet, sieht hCaptcha dessen Netzwerk. Hängen Sie deshalb einen Proxy an die Aufgabe, wenn das für die Website eine Rolle spielt.
Häufig gestellte Fragen
Ist hCaptcha dasselbe wie reCAPTCHA?
Nein. Es sind getrennte Dienste mit eigenen Widgets, Feldnamen und Verifizierungs-Hosts. Ein Skript muss das richtige Feld senden und bei CapSkip die richtige Methode anfordern.
Woran erkenne ich, ob eine Website hCaptcha Enterprise nutzt?
Nicht immer am Frontend. Laut CapSkip-Dokumentation übergeben manche Enterprise-Websites vor dem Start des Widgets einen Wert rqdata an hcaptcha.setData(). Sehen Sie diesen Aufruf, senden Sie den Wert als Option data, bei jeder Aufgabe frisch. Sehen Sie ihn nicht, lösen Sie normal und probieren Sie High score mode, wenn die Website Token ablehnt.
Warum lehnt ein Formular einen Token ab, den CapSkip zurückgegeben hat?
Die CapSkip-Dokumentation nennt die üblichen Ursachen: ein Token, der alt oder schon benutzt ist, ein Sitekey, der nicht zur Seite passt, oder ein User-Agent, der sich von dem in der Antwort unterscheidet. Für strenge Websites nennt sie zusätzlich die Einstellung High score mode für hCaptcha unter Settings, Captcha types, die Google Chrome auf dem CapSkip-PC braucht.
Kann ich CapSkip für hCaptcha-Aufgaben auf einem Server betreiben?
Ja. Verwenden Sie den Server-Modus auf einem Windows-Rechner, den Sie kontrollieren, und richten Sie Ihr Skript auf dessen Adresse.
Die Kurzfassung
hCaptcha ist ein Widget, das in einem einmal verwendbaren Token endet, der einmal an der siteverify-Adresse von hCaptcha geprüft wird. Ein lokaler Captcha-Löser auf Ihrem eigenen Windows-PC deckt die Fälle Checkbox, Invisible und Enterprise mit einer Methode und ohne Gebühr pro Lösung ab.
