Cloudflare Turnstile

Cloudflare Turnstile ist eine datenschutzfreundliche CAPTCHA-Alternative, die Besucher meist ganz ohne Rätsel prüft. Frontmail nutzt sie, um Bots daran zu hindern, Ihren öffentlichen Schlüssel zu missbrauchen.

Ist bei einer Vorlage CAPTCHA verlangen (Turnstile) eingeschaltet, muss jede Anfrage mit öffentlichem Schlüssel an diese Vorlage einen gültigen Turnstile-Token enthalten, sonst schlägt sie mit captcha_required oder captcha_failed fehl, bevor sie Sie einen Credit kostet. Anfragen mit privatem Schlüssel (von Ihrem Server) brauchen nie ein CAPTCHA.

So funktioniert es

Wo das Formular läuft	Wessen Turnstile-Schlüssel	Was Sie tun
Ihre Website	Ihre – ein kostenloses Widget in Ihrem eigenen Cloudflare-Konto	Widget erstellen, beide Schlüssel unter Sicherheit → Bot-Schutz (Turnstile) einfügen, den Site Key in Ihr Formular einbauen.
Mobile App (@frontmail/react-native)	Der gemeinsame mobile Schlüssel von Frontmail	Nichts – <TurnstileWebView> lädt den Schlüssel selbst.

Warum eigene Schlüssel für Websites

Der kostenlose Turnstile-Tarif erlaubt 10 Hostnamen pro Widget und 20 Widgets pro Konto; ein Widget, das auf jedem Hostnamen funktioniert, gibt es nur im Enterprise-Tarif von Cloudflare. Ein einzelner Frontmail-Schlüssel kann daher nicht die Websites aller unserer Kunden abdecken. Ihr eigenes Widget ist kostenlos, in etwa zwei Minuten eingerichtet und funktioniert nur auf den von Ihnen eingetragenen Hostnamen – so kann niemand Ihr CAPTCHA auf einer anderen Website wiederverwenden.

1. Turnstile-Widget in Cloudflare erstellen

1. Melden Sie sich im Cloudflare-Dashboard an (ein kostenloses Konto genügt – Ihre Domain muss Cloudflare nicht nutzen).
2. Öffnen Sie Turnstile und klicken Sie auf Add widget.
3. Geben Sie ihm einen Namen, z. B. Kontaktformular.
4. Tragen Sie alle Hostnamen ein, auf denen Ihr Formular läuft, z. B. example.com und www.example.com. localhost fügen Sie nur hinzu, wenn Sie lokal mit echten Schlüsseln testen möchten – für die lokale Entwicklung können Sie stattdessen Testschlüssel verwenden.
5. Widget mode: Managed passt (Cloudflare zeigt nur dann eine Checkbox, wenn es unsicher ist).
6. Klicken Sie auf Create und kopieren Sie den Site Key und den Secret Key.

2. Schlüssel in Frontmail hinterlegen

1. Öffnen Sie im Frontmail-Dashboard Sicherheit und suchen Sie die Karte Bot-Schutz (Turnstile).
2. Fügen Sie den Site Key und den Secret Key ein und klicken Sie auf Schlüssel speichern.
3. Frontmail prüft den Secret Key sofort bei Cloudflare – ein falscher Secret Key wird mit einer klaren Meldung abgelehnt. Der Secret Key wird verschlüsselt gespeichert und nie wieder angezeigt. Sie können die Schlüssel jederzeit mit Schlüssel ersetzen ändern oder mit Schlüssel entfernen löschen.
4. Klicken Sie nach dem Speichern auf CAPTCHA für alle Vorlagen aktivieren, um das CAPTCHA für alle bestehenden Vorlagen auf einmal einzuschalten. Vorlagen, die als automatische Antwort dienen, werden übersprungen – sie werden von Frontmail gesendet, nicht von Ihrem Formular.

Ab jetzt haben neue Vorlagen das CAPTCHA standardmäßig eingeschaltet. Vorlagen, die vor dem Hinterlegen der Schlüssel erstellt wurden, starten mit ausgeschaltetem CAPTCHA – verwenden Sie den Button oben oder schalten Sie es pro Vorlage im Vorlageneditor unter Einstellungen → Schutz ein.

Ohne Schlüssel lässt der Vorlageneditor das CAPTCHA nicht einschalten und verweist auf die Seite Sicherheit. Die Ausnahme ist Mobile Apps erlauben: Dann können Sie es (mit einer Warnung) einschalten, weil mobile Apps den gemeinsamen Schlüssel von Frontmail verwenden – Anfragen von Websites an diese Vorlage schlagen mit captcha_not_configured fehl, bis Sie Ihre Schlüssel hinterlegen.

3. Widget in Ihr Formular einbauen

Verwenden Sie Ihren Site Key (er ist öffentlich – der Secret Key verlässt Frontmail nie). Der Tab Snippets im Vorlageneditor enthält das Widget mit Ihrem Site Key bereits, wenn die Vorlage das CAPTCHA verlangt.

Mit reinem HTML und sendForm – rendern Sie das Widget innerhalb des Formulars. Turnstile fügt ein verstecktes Feld cf-turnstile-response hinzu, das sendForm automatisch mitsendet:

<form id="contact">
  <!-- Ihre Felder -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button>Senden</button>
</form>

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

Mit den Framework-Komponenten – übergeben Sie Ihren Site Key an FrontmailForm; die Komponente lädt Turnstile, rendert das Widget, sendet den Token und setzt das Widget für Sie zurück:

• React und Svelte: <FrontmailForm turnstileSiteKey="YOUR_TURNSTILE_SITE_KEY" …>
• Vue: <FrontmailForm turnstile-site-key="YOUR_TURNSTILE_SITE_KEY" …>

Mit send() – rendern Sie das Widget selbst und übergeben Sie den Token in den Optionen:

await send('svc_01J9…', 'tpl_contact', params, { turnstileToken: token });

Über die REST-API übergeben Sie turnstile_token im JSON-Body oder cf-turnstile-response in Multipart-Formularen.

Wie Frontmail den Token prüft

Anfragen von einer Website tragen einen Origin- (oder Referer-)Header. Frontmail prüft ihren Token mit Ihrem Secret Key und kontrolliert außerdem, dass Cloudflare das Widget auf demselben Hostnamen gelöst hat, von dem die Anfrage kam. Ein Token von einem anderen Hostnamen schlägt mit captcha_failed fehl (details.reason: "hostname_mismatch") – tragen Sie daher jeden Hostnamen Ihrer Website im Widget ein.

Mobile Apps

@frontmail/react-native braucht keinen Site Key. Seine <TurnstileWebView> holt den mobilen Site Key von Frontmail über GET /v1/public-config (zwischengespeichert) und zeigt das Widget als Inline-Seite mit der URL https://mobile.frontmail.dev an. Native Anfragen haben keinen Origin-Header. Schalten Sie Mobile Apps erlauben ein – ohne diese Einstellung werden solche Anfragen schon vor der CAPTCHA-Prüfung abgelehnt (auch wenn keine erlaubten Websites eingetragen sind). Nur dann prüft Frontmail sie mit seinem gemeinsamen mobilen Secret; bei einer Organisation, die mobile Apps nicht erlaubt hat, wird das CAPTCHA nie gegen das gemeinsame, öffentlich verfügbare Widget geprüft.

Eigener Schlüssel in der App

Sie können Ihr eigenes Widget auch in der App verwenden: Übergeben Sie <TurnstileWebView> einen siteKey und eine baseUrl, deren Hostname in Ihrem Widget eingetragen ist (z. B. https://example.com). Das SDK kennzeichnet die Anfrage dann automatisch mit turnstile_key: "org", und Frontmail prüft sie mit Ihrem Secret Key.

Andere native Clients (Flutter, Swift, Kotlin …), die die REST-API direkt aufrufen, können dasselbe tun: Ihr Widget in einer WebView rendern und turnstile_key: "org" zusammen mit turnstile_token senden.

Lokale Entwicklung

Cloudflare veröffentlicht Testschlüssel, die offline und auf jedem Hostnamen funktionieren:

Schlüssel	Wert	Ergebnis
Site Key	1x00000000000000000000AA	besteht immer
Secret Key	1x0000000000000000000000000000000AA	besteht immer
Secret Key	2x0000000000000000000000000000000AA	scheitert immer

Frontmail akzeptiert sie in Entwicklungsumgebungen unter Sicherheit → Bot-Schutz (Turnstile).

Testschlüssel werden in Produktion abgelehnt

Testschlüssel lassen jede Anfrage durch – sie schalten den Schutz ab. Der Produktivdienst weigert sich daher, sie zu speichern (400, details.reason: "test_keys"), und eine Vorlage, deren Organisation noch einen Test-Secret-Key gespeichert hat, schlägt mit captcha_not_configured (details.reason: "test_secret") fehl, bis Sie die Schlüssel eines echten Widgets hinterlegen.

In automatisierten Tests können Sie stattdessen auch mit einem privaten Schlüssel senden – Anfragen mit privatem Schlüssel überspringen die Prüfung.

Tokens

• Ein Token ist etwa 5 Minuten gültig und kann einmal verwendet werden.
• Setzen Sie das Widget nach jeder Sendung (ob erfolgreich oder nicht) vor dem nächsten Versuch zurück (turnstile.reset()). Die Framework-Komponenten tun das automatisch.
• Wiederholungen derselben logischen Sendung durch das SDK verwenden denselben Idempotenzschlüssel. Eine wiederholte Anfrage, die bereits angenommen wurde, wird noch vor der Turnstile-Prüfung mit der Antwort des ersten Versuchs beantwortet – ein bereits verbrauchter Token lässt die Wiederholung also nicht scheitern.

Fehler

Code	Status	Wann	Lösung
captcha_required	403	Die Vorlage verlangt das CAPTCHA und die Anfrage hat keinen Token.	Widget ins Formular einbauen oder turnstileToken übergeben.
captcha_failed	403	Cloudflare hat den Token abgelehnt – ungültig, abgelaufen, bereits verwendet oder auf einem anderen Hostnamen gelöst (hostname_mismatch).	Widget zurücksetzen und erneut versuchen; alle Ihre Hostnamen im Widget eintragen.
captcha_not_configured	403	Eine Website-Anfrage an eine Vorlage mit eingeschaltetem CAPTCHA, aber Ihre Organisation hat keine Turnstile-Schlüssel (oder in Produktion nur Cloudflare-Testschlüssel).	Schlüssel eines echten Widgets unter Sicherheit → Bot-Schutz (Turnstile) hinterlegen.

Ausschalten

Sie können CAPTCHA verlangen (Turnstile) pro Vorlage im Vorlageneditor unter Einstellungen → Schutz ausschalten – etwa für Vorlagen, die nur von Ihrem Server gesendet werden. Für öffentliche Formulare empfehlen wir dringend, es eingeschaltet zu lassen.

Im Dashboard

Die Schlüssel beschreibt Sicherheitseinstellungen, die Vorlageneinstellungen der Vorlageneditor.