ReCaptcha

Das Modul recaptcha beinhaltet einen Tag, der sich nahtlos in die APF-Formulare integriert. Die Konfiguration des Feldes und der Validierung kann dabei wie gewohnt vorgenommen werden.

ReCaptcha ist ein CAPTCHA-Service, der unter http://www.google.com/recaptcha von Google angeboten wird. Der vom Service angebotene Touring-Test gilt als derzeit sicherste Implementierung zur Abwehr von SPAM.

Die folgenden Kapitel beschreiben die Einbindung und Konfiguration im Detail.

1. ReCaptcha-Key

Um ReCaptcha nutzen zu können, registrieren Sie bitte zunächst einen Account unter https://www.google.com/recaptcha/admin/create. Falls Sie noch keinen Google-Account besitzten, haben Sie dort die Möglichkeit einen solchen zu erstellen.

ReCaptcha-Key Antragsformular

Füllen Sie das angezeigte Formularfeld aus und bestätigen Sie die Eingabe mit Klick auf den Button. Anschließend wird Ihnen der generierte Schlüssel angezeigt. Sofern der Schlüssel für mehrere Domains gelten soll, befolgen Sie die beschriebenen Anweisungen.

ReCaptcha Schlüssel

Speichern oder merken Sie sich die generierten Schlüssel, denn Sie werden sie im Folgenden zur Konfiguration des ReCaptcha-Feldes brauchen.

2. Einbindung

2.1. Basis-Konfiguration

Die Implementierung der APF-ReCaptcha-Funktionalität basiert auf der externen Bibliothek recaptchalib, die unter https://developers.google.com/recaptcha/ bezogen werden kann.

Zur Aktivierung der Funktionalität laden Sie sich die bitte von der angebenen Adresse herunter und legen diese in Ihrem Projekt ab. Anschließend binden Sie die Datei wie folgt z.B. in Ihrer Bootstrap-Datei ein, damit die Klassen ReCaptchaTag und ReCaptchaValidator auf die Funktionalität zurückgreifen können:

PHP-Code
include('./external-libs/google/recaptcha/recaptchalib.php');

2.2. Nutzung innerhalb von Formularen

Zur Einbindung des ReCaptcha-Service bringt das Modul einen Tag mit, der sich nicht wesentlich von anderen Tags der Formular-Unterstützung unterscheidet. Er hat folgende Signatur:

APF-Template
<form:recaptcha name="" public-key="" private-key="" theme="" [custom-theme-id=""] [tabindex=""] />
Beschreibung der Attribute:

Um das Feld innerhalb eines <html:form />-Tags nutzen zu können, muss dieses zunächst per

APF-Template
<form:addtaglib class="APF\modules\recaptcha\pres\taglib\ReCaptchaTag" prefix="form" name="recaptcha" />

bekannt gegeben werden. Anschließend können Sie das Feld wie folgt nutzen:

APF-Template
<core:addtaglib class="APF\tools\form\taglib\HtmlFormTag" prefix="html" name="form" /> <html:form name="newsletter-signup"> <form:error> <p class="error"> Das Formular wurde <strong>nicht</strong> korrekt ausgefüllt! </p> </form:error> <form:success> <p class="error"> Das Formular wurde korrekt ausgefüllt. </p> </form:success> <p> <label for="email">E-Mail-Adresse</label> <form:text name="email" id="email"/> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="email" button="send" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" /> </p> <p> <form:addtaglib class="APF\modules\recaptcha\pres\taglib\ReCaptchaTag" prefix="form" name="recaptcha" /> <form:recaptcha name="re-captcha" public-key="123456789012341-0000000000-ABCDE8764Rfc3" private-key="123456Rt3012341-1111111111-ABCDE8764Rfc-P" theme="white" /> <form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="re-captcha" button="send" /> </p> <p> <form:button name="send" value="Abschicken" /> </p> </html:form>
Bitte beachten Sie, dass die angegebenen Public- und Private-Keys Beispiele sind und nicht für Ihr Applikation genutzt werden können. Bitte registrieren Sie zur Einbindung ein Key-Paar wie im Kapitel 1 beschrieben.

Zur Anzeige und Verarbeitung des Formulars ist folgender (Document-)Controller notwendig:

PHP-Code
class NewsletterController extends BaseDocumentController { public function transformContent() { $this->getForm('newsletter-signup')->transformOnPlace(); } }

3. Validierung

Wie in Kapitel 2 bereits angedeutet, beinhaltet das Modul recaptcha einen Validator für das ReCaptcha-Control. Wie im Modul CAPTCHA-Taglib (für Formulare) ist es auch hier zwingend notwendig einen Validator zu definieren.

Wird kein Validator für das ReCaptcha-Feld im Formular definiert, ist es wirkungslos und Angreifer können das Formlar ungeschützt aufrufen.

Die Validierung basiert - genauso wie die Generierung der Ausgabe - auf der reCAPTCHA PHP library. Zur einfacheren Verwendung und Einbindung beinhaltet das vorliegende Modul einen Wrapper für APF-Formular-Validatoren. Dieser kann wie folgt auf ein Formular-Element angewendet werden:

APF-Template
<form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="..." button="..." />

Das Attribut control referenziert das gewünschte ReCaptcha-Feld (siehe Kapitel 2) und button denjenigen Button, der das Validierungs-Event auslösen soll. Details zu Formular-Validatoren finden Sie unter Formulare.

4. Anpassung

Das Google ReCaptcha-Feld lässt sich sehr einfach anpassen. Hierzu stehen bei der Nutzung des APF-Formular-Element eigene Attribute zur Verfügung.

4.1. Themes

Das ReCaptcha-Element verfügt gemäß Dokumentation unter https://developers.google.com/recaptcha/docs/customization?hl=de#Standard_Themes über folgende Themes:

  • red (standard)
  • white
  • blackglass
  • clean

Diese können mit Hilfe des Attributes theme des <form:recaptcha />-Tags definiert werden.

Sofern Sie ein eigenes Theme definieren möchten, beachten Sie bitte die Hinweise unter https://developers.google.com/recaptcha/docs/customization?hl=de#Custom_Theming. Verwenden Sie ein eigenes Theme, so muss das Attribut theme mit dem Wert custom gefüllt werden.

4.2. Internationalisierung

Das ReCaptcha-Element unterstützt bereits viele Sprachen out-of-the-box. Bei der Generierung des Feldes übergibt der <form:recaptcha />-Tag die aktuell ausgewählte Sprache aus dem Feld $this->language. Zur Steuerung der Sprache können Sie z.B. den unter http://wiki.adventure-php-framework.org/Sprache_per_FC-Action_%C3%A4ndern beschriebenen Code nutzen.

Nutzen Sie keine dynamische Sprachumschaltung, so ist die Sprache entscheiden, die in der Bootstrap-Datei per

PHP-Code
$fC = &Singleton::getInstance('Frontcontroller'); ... $fC->setLanguage('xyz'); ...

definiert wird.

4.3. Eigene Übersetzungstexte

4.3.1. Konfiguration per Attribut

Neben der in Kapitel 4.2 beschriebenen Übersetzung ist es möglich, eigene Texte für die unterschiedlichen Fehlerfälle zu definieren. Hierzu stehen Ihnen folgende Tag-Attribute zur Verfügung:

Attribut JavaScript-Option Bedeutung
label-instructions-visual instructions_visual Label für das CAPTCHA-Bild.
label-instructions-audio instructions_audio Label für das CAPTCHA-Audio.
label-play-again play_again Label für das erneute Abspielen des Audio-CAPTCHA.
label-cant-hear-this cant_hear_this Label für das Neu-Laden eines Audio-CAPTCHA.
label-visual-challenge visual_challenge Label für den Button zum Wechsel zum Bild-CAPTCHA.
label-audio-challenge audio_challenge Label für den Button zum Wechsel zum Audio-CAPTCHA.
label-refresh-btn refresh_btn Alternativ-Text des Neu-Laden-Buttons.
label-help-btn help_btn Label des Hilfe-Buttons.
label-incorrect-try-again incorrect_try_again Text der Fehlermeldung für ein falsch gelöstes CAPTCHA.

Die in der Tabelle aufgeführten Attribute können wie folgt verwendet werden:

APF-Template
<form:recaptcha name="my-captcha" ... [label-instructions-visual=""] [label-instructions-audio=""] [label-play-again=""] [label-cant-hear-this=""] [label-visual-challenge=""] [label-audio-challenge=""] [label-refresh-btn=""] [label-help-btn=""] [label-incorrect-try-again=""] />
Die einzelnen Attribute sind jeweils optional (daher mit Klammern versehen). Sofern ein Attribut nicht angegeben wurde, wird der Standard-Wert für die aktuell aktive Sprache genutzt.
4.3.2. Konfiguration per Tag

Alternativ zur Definition von eigenen Übersetzungstexten per Attribut im Template, können die Texte auch in eine eigene Sprach-Datei ausgelagert werden. Hierzu bringt der <form:recaptcha />-Tag eine eigene <recaptcha:getstring />-Implementierung mit:

APF-Template
<form:recaptcha name="my-captcha"> <recaptcha:getstring namespace="" config="" entry="" /> </form:recaptcha>

Die Attribute des <recaptcha:getstring />-Tags sind identisch zur Definition des <html:getstring />. Um Texte mit Hilfe des <recaptcha:getstring />-Tags mit eigenen Übersetzungen zu bestücken, legen Sie bitte eine Sprach-Datei mit den gewünschten Sprachen und Texten an. Für den Anwendungsfall

APF-Template
<form:recaptcha name="my-captcha"> <recaptcha:getstring namespace="APF\sites\my-site\pres" config="recaptcha_labels.ini" entry="guestbook" /> </form:recaptcha>

erwartet der Tag eine Konfiguration mit dem Namen {ENVIRONMENT}_recaptcha_labels.ini unter config/sites/my-site/pres/{CONTEXT}/. Soll das ReCaptcha in Deutsch und Englisch angeboten werden, gestaltet sich der Inhalt der Datei wie folgt:

APF-Konfiguration
[de] guestbook.label-instructions-visual="" guestbook.label-instructions-visual="" guestbook.label-instructions-audio="" guestbook.label-play-again="" guestbook.label-cant-hear-this="" guestbook.label-visual-challenge="" guestbook.label-audio-challenge="" guestbook.label-refresh-btn="" guestbook.label-help-btn="" guestbook.label-incorrect-try-again="" [en] guestbook.label-instructions-visual="" guestbook.label-instructions-visual="" guestbook.label-instructions-audio="" guestbook.label-play-again="" guestbook.label-cant-hear-this="" guestbook.label-visual-challenge="" guestbook.label-audio-challenge="" guestbook.label-refresh-btn="" guestbook.label-help-btn="" guestbook.label-incorrect-try-again=""

Die Sektionen de und en beinhalten die Labels für die unterschiedlichen Sprachen und kann jederzeit um weitere Sprachen erweitert werden. Die Subsektion der jeweiligen Sprache - im Beispiel guestbook - beschreibt den Anwendungsfall des CAPTCHAs. Dies ermöglicht die zentrale Definition von Labels für unterschiedliche Einsatzzwecke in einer Datei.

Die Subsektion der jeweiligen Sprache wird über das Attribut entry referenziert, die darunter definierten Attribute sind identisch mit den im Tag direkt genutzten Konfigurationsmöglichkeiten (siehe Tabelle Kapitel 4.3.1).

Die einzelnen Attribute sind auch bei der Verwendung des <recaptcha:getstring />-Tags jeweils optional. Sofern ein Attribut nicht angegeben wurde, wird der Standard-Wert für die aktuell aktive Sprache genutzt.

Details zur Definition von Konfigurationen und zum Umgang mit Kontext ({CONTEXT}) und Umgebung ({ENVIRONMENT}) finden Sie unter Konfiguration.

4.4. Tab-Index

Das ReCaptcha-Element unterstützt die Definition der Feld-Reihenfolge für die Verwendung der Tab-Taste. Um den Index festzulegen, definieren Sie bitte das tabindex-Attribut des <form:recaptcha />-Feldes mit der gewünschten Nummer.

4.5. SSL-Nutzung

Um die Nutzung der SSL-basierten ReCaptcha-API zu aktivieren, nutzen Sie bitte das Attribut use-ssl. Ist dieses auf den Wert true gesetzt, wird die SSL-basierte API des Google ReCaptcha-Service genutzt. Ist das Attribut nicht vorhanden, wird der HTTP-Service genutzt.

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
Für diesen Artikel liegen aktuell keine Kommentare vor.