Tutorials

Cloudflare Turnstile einrichten: Schritt-für-Schritt-Anleitung für die kostenlose reCAPTCHA-Alternative

Melden

Cloudflare Turnstile ist eine moderne, datenschutzfreundliche (DSGVO-konforme) und völlig kostenlose Alternative zu Google reCAPTCHA. Besucher müssen keine nervigen Ampeln oder Zebrastreifen mehr anklicken – in den meisten Fällen läuft die Überprüfung komplett unsichtbar im Hintergrund ab.

In dieser Anleitung erfährst du Schritt für Schritt, wie du Turnstile erstellst und auf deiner Website einbindest.

Voraussetzungen

  • Ein kostenloser Cloudflare-Account (deine Website muss nicht über das Cloudflare-DNS laufen, um Turnstile nutzen zu können).
  • Zugriff auf den Quellcode deiner Website (Frontend und Backend).

Schritt 1: Turnstile im Cloudflare-Dashboard anlegen

  1. Einloggen: Melde dich in deinem Cloudflare Dashboard an.
  2. Turnstile auswählen: Klicke in der linken Navigationsleiste auf Turnstile.
  3. Widget hinzufügen: Klicke auf den Button Add site (oder Site hinzufügen).
  4. Details eingeben:
    • Site name: Ein interner Name für dein Projekt (z. B. „Kontaktformular Hauptseite“).
    • Domain: Gib hier deine Domain ein (z. B. deine-website.de). Du kannst für lokale Tests auch localhost hinzufügen.
    • Widget Mode: Wähle die Art der Überprüfung:
      • Managed (Empfohlen): Cloudflare entscheidet automatisch, ob eine unsichtbare Prüfung reicht oder ein Klick auf eine Checkbox nötig ist.
      • Non-interactive: Nur ein Ladebalken, keine Interaktion des Nutzers erforderlich.
      • Invisible: Komplett unsichtbar im Hintergrund.
  5. Erstellen: Klicke auf Create (Erstellen).

Nach dem Erstellen erhältst du zwei wichtige Schlüssel:

  • Sitekey (Öffentlicher Schlüssel): Wird im HTML-Code deiner Website eingebunden.
  • Secret Key (Geheimer Schlüssel): Wird ausschließlich auf deinem Webserver zur Verifikation verwendet. Niemals öffentlich teilen!

Schritt 2: Frontend-Integration (HTML)

Um Turnstile in ein bestehendes Formular einzubinden, sind nur zwei Zeilen Code nötig.

1. Das Skript einbinden

Füge folgendes Skript im <head>-Bereich deiner Website oder direkt vor dem schließenden </body>-Tag ein:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

2. Das Widget im Formular platzieren

Füge das Turnstile-Element an der Stelle deines Formulars ein, an der die Prüfung erfolgen soll (meist direkt vor dem Absende-Button):

<form action="/formular-absenden" method="POST">
    <!-- Deine Formularfelder (Name, E-Mail etc.) -->
    <input type="text" name="name" required placeholder="Dein Name">

    <!-- Turnstile Widget -->
    <div class="cf-turnstile" data-sitekey="HIER_DEINEN_SITEKEY_EINTRAGEN"></div>

    <button type="submit">Absenden</button>
</form>

Ersetze HIER_DEINEN_SITEKEY_EINTRAGEN mit deinem tatsächlichen Sitekey aus Schritt 1.

Sobald der Nutzer das Formular absendet, generiert Turnstile ein Token und sendet dieses im versteckten POST-Feld cf-turnstile-response an deinen Server.

Schritt 3: Backend-Validierung (Server)

Wichtig: Das Einbinden im Frontend allein schützt nicht vor Spam! Dein Server muss das generierte Token bei Cloudflare validieren, bevor das Formular verarbeitet wird.

Hier ist ein einfaches Beispiel für die Überprüfung in PHP:

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $turnstile_response = $_POST['cf-turnstile-response'] ?? '';
    $secret_key = 'HIER_DEINEN_SECRET_KEY_EINTRAGEN';
    $remote_ip = $_SERVER['REMOTE_ADDR'];

    // Validierungsanfrage an Cloudflare senden
    $url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
    $data = [
        'secret' => $secret_key,
        'response' => $turnstile_response,
        'remoteip' => $remote_ip
    ];

    $options = [
        'http' => [
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($data)
        ]
    ];

    $context  = stream_context_create($options);
    $verify_result = file_get_contents($url, false, $context);
    $response_data = json_decode($verify_result);

    // Auswertung
    if ($response_data->success) {
        // Erfolg: Formular verarbeiten (z. B. E-Mail senden oder DB-Eintrag)
        echo "Erfolgreich verifiziert! Vielen Dank für deine Nachricht.";
    } else {
        // Fehlgeschlagen: Bot-Verdacht
        echo "CAPTCHA-Überprüfung fehlgeschlagen. Bitte versuche es erneut.";
    }
}
?>

Schritt 4: Testen

Cloudflare bietet Test-Keys an, mit denen du dein Formular vor dem Livegang risikofrei testen kannst, ohne dein Kontingent zu belasten oder blockiert zu werden:

  • Sitekey (Erfolg immer erzwingen): 1x00000000000000000000AA
  • Secret Key (Erfolg immer erzwingen): 1x0000000000000000000000000000000AA

Wenn du diese Dummy-Keys nutzt, wird die Prüfung immer positiv (success: true) ausfallen.

Zusammenfassung

Cloudflare Turnstile ist in unter 15 Minuten eingerichtet:

  1. Schlüssel im Dashboard anfordern.
  2. JS-Skript und <div>-Container im HTML-Formular platzieren.
  3. Den cf-turnstile-response-Wert auf dem Server gegen die Cloudflare-API abgleichen.

Damit ist dein Formular zuverlässig vor Spam-Bots geschützt, ohne deine Besucher mit nervigen Bilderrätseln zu frustrieren.

0