CaptchaFox Extension für TYPO3

Sie können die Formulare Ihrer TYPO3-Website mit der offiziellen CaptchaFox-Extension schützen. Sie ergänzt das TYPO3-Formular-Framework (EXT:form) um ein Element „CaptchaFox“ und prüft die Antwort auf dem Server, bevor das Formular angenommen wird.

Anforderungen

TYPO3	Extension-Version	PHP
14.3 oder neuer	14.x	8.2 oder neuer
12.4 LTS und 13.4 LTS	12.x	8.1 oder neuer
10.4.11+ und 11.5.7+	10.x (nur Sicherheitsfixes)	7.4 oder neuer

Installation

Installieren Sie die Extension mit Composer oder aus dem TYPO3 Extension Repository. Composer wählt die Version, die zu Ihrer TYPO3-Version passt:
```
composer require captchafox/captchafox-typo3
```
Kopieren Sie im CaptchaFox-Portal den Site Key Ihrer Website (Sites) und den Secret Key Ihrer Organisation (Organization Settings).
Tragen Sie beide Schlüssel unter Verwaltungswerkzeuge > Einstellungen > Extension Configuration > captchafox_official ein (TYPO3 14: System > Einstellungen > Extension Configuration).
Fügen Sie das Element CaptchaFox im Formular-Editor zu Ihren Formularen hinzu.
Alles ist eingerichtet. Ihre Formulare sind jetzt geschützt!

Ein statisches Template muss nicht eingebunden werden. Bis zu den Versionen 10.0.2 und 12.0.1 war das statische Template „CaptchaFox-Typo3“ nötig; eine bestehende Einbindung schadet nicht.

Konfiguration

Option	Standard	Beschreibung
`site_key`	öffentlicher Testschlüssel	Site Key aus dem CaptchaFox-Portal (Sites)
`secret_key`	öffentlicher Testschlüssel	Secret Key Ihrer CaptchaFox-Organisation
`lang`	leer (10.x: `de`)	Sprachcode des Widgets, z. B. `de`. Leer: die Sprache der aktuellen Site-Sprache (10.x: die Browsersprache)
`apiUnavailable`	`allow`	Wenn CaptchaFox keine verwertbare Antwort liefert (Netzwerkfehler, Timeout nach 5 Sekunden, Serverfehler): `allow` lässt das Formular durch, `block` lehnt es ab. Antworten, die CaptchaFox ablehnt, werden immer abgelehnt. Beide Fälle werden ins TYPO3-Log geschrieben.
`robotMode`	aus	Schaltet CaptchaFox für alle Besucher ab, nur für automatisierte Tests. Niemals auf einer Live-Website aktivieren.
`enforceCaptcha`	aus	Ohne diese Option wird CaptchaFox im Development-Kontext von TYPO3 weder angezeigt noch geprüft.

⚠️

Die Standardschlüssel sind die öffentlichen Testschlüssel: Das Widget zeigt „For testing purposes only.“, und nichts ist geschützt, bis Sie Ihre eigenen Schlüssel eintragen.

Mehrere Sites (Multi-Domain)

Ab den Versionen 12.1.0 und 14.0.0 (TYPO3 12 oder neuer) kann jede Site einer Installation eigene Schlüssel verwenden. Site-Einstellungen überschreiben die Extension-Konfiguration; jeder Wert, den eine Site nicht setzt, fällt auf sie zurück. Meist unterscheidet sich nur der Site Key, weil der Secret Key zur CaptchaFox-Organisation gehört.

config/sites/<site>/settings.yaml:

captchafox:
  siteKey: 'sk_…'
  # Nur wenn diese Site zu einer anderen CaptchaFox-Organisation gehört. Secrets nicht versionieren:
  secretKey: '%env(CAPTCHAFOX_SECRET_KEY_EXAMPLE_COM)%'

Ab TYPO3 13 lassen sich beide Werte auch im Backend bearbeiten: Fügen Sie der Site das Set „CaptchaFox“ (captchafox/captchafox) hinzu und öffnen Sie Seitenverwaltung > Einstellungen (TYPO3 13) bzw. Websites > Site-Einstellungen bearbeiten (TYPO3 14). Der Editor zeigt den Secret Key im Klartext; der %env()%-Verweis oben vermeidet das.

Nutzung

Fügen Sie das Element CaptchaFox im Formular-Editor zu einem Formular hinzu. Das Element prüft die Antwort immer, auch wenn sein Validator aus der Formulardefinition entfernt wurde. Mehrere Formulare mit CaptchaFox auf einer Seite funktionieren unabhängig voneinander.

Hinweise für den Betrieb

Reverse Proxys: Die IP-Adresse des Besuchers wird an CaptchaFox übermittelt. Hinter einem Proxy oder Load Balancer konfigurieren Sie $GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'], sonst wird die Adresse des Proxys übermittelt.
Content Security Policy: Sendet Ihre Website eine Content Security Policy, erlauben Sie die unter Content Security Policy aufgeführten Quellen.
Das Widget-Skript wird von https://cdn.captchafox.com/api.js geladen; es kann nicht gebündelt oder selbst gehostet werden.

Keycloak ReachFive