POWER CAPTCHA Integration

mit WordPress, TYPO3 oder JavaScript

POWER CAPTCHA INSTALLATION

Einfache Integration

POWER CAPTCHA ist mit allen Systemen kompatibel, die mit externen Schnittstellen kommunizieren können. Deine Website muss somit keine besonderen Voraussetzungen erfüllen um POWER CAPTCHA zu verwenden. Wenn du POWER CAPTCHA in deine Website einbindest, interagiert deine Website mit unserem Server, und wir können deine Website schützen. Um die Anwendung zu installieren, musst du dir zunächst eine Lizenz sichern. Mit deiner Lizenz, erhältst du automatisch einen API-Schlüssel, um unsere Schnittstellen anzusprechen. Du kannst POWER CAPTCHA anschließend auf verschiedene Arten in deine Website / Applikation integrieren: Wenn du WordPress oder TYPO3 nutzt, lade dir einfach unser Plugin bzw. die Extension herunter und folge unserer Installationsanleitung. Du benötigst hierfür keine Programmierkenntnisse. Weiterhin kannst du POWER CAPTCHA über JavaScript einbinden und das Token auf dem Server z.B. mit PHP oder Java verifizieren. Hierfür kannst du ebenfalls unsere Vorlagen nutzen.

Installationsanleitungen und Konfiguration

Die POWER CAPTCHA Extension für deine TYPO3-Installation kannst du direkt bei TYPO3 herunterladen. Alternativ findest du die Extension, sowie eine Kurzanleitung zur Einbindung, auch im GitHub Repository. Unsere Integration ist mit den TYPO3 Versionen 11.5 LTS und 12.4 LTS kompatibel und schützt Formulare, die du mit den Erweiterungen „Form“ oder „Powermail“ erstellst. Durch die Integration stellen wir ein neues Feld zur Verfügung, welches du einfach in deine Formulare hinzufügst.

Im unteren Bereich dieser Seite findest du Schritt-für-Schritt-Anleitungen zur Installation mit WordPress und JavaScript sowie zur Token-Verifizierung mit PHP oder über die Verifiy-Schnittstelle. Diese kannst du direkt verwenden bzw. für deinen Bedarf anpassen. Wenn du OXID eShop Kunde bist, kannst du hier unserer Integrationsanleitung für das OXID-Modul folgen.

Du kannst mit POWER CAPTCHA nicht nur klassische Websites oder Shops, sondern diverse Systeme schützen, die eine Cloud-Oberfläche haben. Grundsätzlich ist POWER CAPTCHA mit allen Systemen kompatibel, die mit externen Schnittstellen kommunizieren können. Hier findest du zum Beispiel eine Integrationsanleitung für die Integration in die CRM-Software Vtiger.

Mit dem Erwerb einer Lizenz erhältst du automatisch einen Kunden-Account auf unserer Website. Wenn du POWER CAPTCHA konfigurieren möchtest (Professional- und Enterprise-Versionen), kannst du in deinen Account-Einstellungen die gewünschten Einstellungen vornehmen. Alternativ kannst du auch mit unseren Voreinstellungen starten. Auf der Seite Funktionen findest du einige Konfigurationsbeispiele.

Systembeschreibung

Du möchtest wissen, wie deine Website mit unserem Server kommuniziert? Erfahre mehr in unserem kostenfreien Whitepaper!

INSTALLATION WORDPRESS-PLUGIN FÜR POWER CAPTCHA

WordPress-Plugin installieren

Um das WordPress-Plugin zu installieren, lade dir zunächst das Plugin als ZIP-Datei in unserem Kunden-Bereich herunter. Gehe anschließend in den Administrations-Bereich / Dashboard von WordPress und klicke auf den Menüpunkt Plugins > Installieren. Klicke dort oben auf den Button „Plugin hochladen“ und wähle das ZIP-Archiv aus, welches du zuvor von unserer Website heruntergeladen hast. Im Anschluss klickst du auf „Jetzt installieren“. Nach dem Upload und der Installation öffnet sich eine Seite, über die du unser POWER CAPTCHA-Plugin aktivieren kannst.

Konfiguration des Plugins

Nach der Aktivierung kannst du das Plugin konfigurieren. Dafür gehst du im Administrations-Bereich von WordPress auf Einstellungen > POWER CAPTCHA und trägst dort unter „General settings“ deinen API- und Secret-Key in die entsprechenden Felder ein. Beide Keys erhältst du im Kunden-Bereich unserer Website. Unter „Integration settings“ kannst du auswählen, für welches Plugin oder für welchen Seitenbereich du POWER CAPTCHA aktivieren möchtest.

Der Punkt „Enterprise settings“ ist nur relevant, falls du eine Enterprise-Lizenz hast und die Anwendung nicht als Cloud-Lösung nutzt (Standard), sondern eine lokale POWER CAPTCHA-Instanz betreibst. In diesem Fall hast du die Möglichkeit, die URLs zu deiner lokal gehosteten Instanz und zu deinem lokalen JavaScript einzugeben. Dann gehen alle Requests an deine eigene Instanz, statt an unseren Server. Falls du keine eigene Instanz betreibst, müssen alle Felder unter „Enterpise settings“ leer bleiben. Wenn alle Einstellungen bearbeitet sind, klicke auf „Änderung speichern“. POWER CAPTCHA schützt nun die von dir gewählten Plugins / Bereiche.

Diese WordPress-Bereiche kannst du bereits mit POWER CAPTCHA schützen:

Wordpress Registrierung
Wordpress Login
WooCommerce Registrierung
WooCommerce Login
WooCommerce Passwort zurücksetzen
WPForms
Elementor Pro Forms

Wir arbeiten zurzeit an der Unterstützung folgender Plugins / Bereiche:

Wordpress Kommentar-Funktion
Plugins: Contact Form 7, Ninja Forms, CoBlocks Form, Formidable Forms, Ultimate Member, Fluent Forms

Stand: Juni 2024, Änderungen vorbehalten.

POWER CAPTCHA INTEGRATION MIT HTML UND PHP

Integration im Frontend mit HTML

Um POWER CAPTCHA im Frontend mit HTML zu integrieren, binde zunächst unser JavaScript im <head> Element ein:

				
					<script src="https://cdn.power-captcha.com/v1/power-captcha-1.2.2.min.js" type="text/javascript"></script>

Füge dem zu schützenden Formular ein div-Element hinzu, innerhalb dieses Elements wird das Widget angezeigt. Das div-Element muss mindestens die Attribute data-pc-sitekey=”deinSiteKey” und data-pc-client-uid=”eindeutigeClientId” enthalten. Die eindeutige Client-ID kann zum Beispiel auf der IP-Adresse des Clients basieren. Wichtig ist, dass der Client damit eindeutig identifiziert werden kann und derselbe Wert bei der Token-Verifizierung übergeben wird. Beispiel:

				
					<form method="post" action="submit.php">
    ...
    <div data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
         data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>">
    </div>
    ...
</form>

Falls du eine Enterprise-Lizenz hast, kannst du für zusätzlichen Schutz das Input-Feld mit dem Benutzernamen / der E-Mail-Adresse mit dem Attribut data-pc-user versehen. Beispiel:

				
					<input name="username" type="text" required="required" data-pc-user="" />

Ein Login-Formular, welches mit POWER CAPTCHA geschützt ist, könnte beispielsweise so aussehen:

				
					<form method="post" action="submit.php">
    <label for="username">Username:</label><br />
    <input type="text" id="username" name="username" data-pc-user /><br />
    <label for="password">Password:</label><br />
    <input type="password" id="password" name="password" />
    <div data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
         data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>">
    </div>
    <input type="submit" value="submit" />
</form>

Nach der Sicherheitsprüfung durch die POWER CAPTCHA-API, wird dem Formular ein Feld mit einem Token hinzugefügt. Prüfe dieses Token anschließend im Backend (siehe “Prüfung des Tokens”).

Einstellung des Prüfmodus / Widget verstecken

Standardmäßig ist das POWER CAPTCHA Widget immer eingeblendet und die Sicherheitsprüfung startet automatisch, sobald das Formular ausgefüllt wird (focus Event). Wenn du ein Feld mit dem Attribut data-pc-user versiehst, startet die Prüfung erst, nachdem das Feld ausgefüllt wurde.

Du hast jedoch die Möglichkeit die Anzeige und das Prüfverhalten individuell einzustellen. Dabei kannst du zwischen drei Prüfmodi wählen, um z.B. die automatische Sicherheitsprüfung abzuschalten oder das Widget nur anzuzeigen, wenn es notwendig ist. Du kannst den Prüfmodus über das Attribut data-pc-check-mode einstellen. Du kannst zwischen den Werten “auto”, “hidden” oder “manu” wählen. Dabei steht jeder Wert für einen bestimmten Prüfmodus:

Prüfmodus	Beschreibung
auto	Das Widget ist standardmäßig eingeblendet. Die Sicherheitsprüfung startet, sobald das Formular ausgefüllt wird oder nachdem das Feld (z.B. Benutzername oder E-Mail-Adresse) ausgefüllt wurde. Ein manueller Klick auf das Widget ist nur dann notwendig, wenn auch ein Captcha gelöst werden muss.
hidden	Das Widget ist zunächst nicht eingeblendet. Die Sicherheitsprüfung startet, sobald das Formular ausgefüllt wird oder nachdem das Feld (z. B. Benutzername oder E-Mail-Adresse) ausgefüllt wurde. Falls die Prüfung ergibt, dass ein Captcha gelöst werden muss, wird das Widget angezeigt.
manu	Das Widget ist immer eingeblendet. POWER CAPTCHA startet die Sicherheitsprüfung erst nach einem manuellen Klick auf das Widget.

Hier ein Beispiel, wie du das Widget versteckst (Prüfmodus hidden):

				
					<form method="post" action="submit.php">
    ...
    <div data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
         data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>"
         data-pc-check-mode="hidden">
    </div>
    <input type="submit" value="submit" />
</form>

PRÜFUNG DES TOKENS (PHP)

POWER CAPTCHA Token auf dem Server verifizieren

Bevor du den Inhalt deines Formulars im Backend evaluierst bzw. abspeicherst, solltest du das POWER CAPTCHA Token verifizieren.

Dazu muss das Token aus dem Formular ($_POST[“pc-token”]) und dein Secret-Key an unsere Schnittstelle https://api.power-captcha.com/pcu/v1/verify als JSON übergeben werden, und im Header muss dein Sitekey im Feld X-API-Key vorhanden sein.

Die Schnittstelle gibt ein JSON zurück, im Feld „success“ steht, ob das Token erfolgreich verifiziert wurde. Im Anschluss kannst du dein Formular wie gewohnt evaluieren.

Hier ein Beispiel-Code, wie du ein Token mit PHP verifizieren kannst:

				
					<?php
if(isset($_POST['pc-token']) && !empty($_POST['pc-token'])) {
    $curl = curl_init('https://api.power-captcha.com/pcu/v1/verify');
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl, CURLOPT_POST, TRUE);
    
    curl_setopt($curl, CURLOPT_HTTPHEADER, array(
        'X-API-Key: 5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs', // your api key
        'Content-Type: application/json'
    ));
    
    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode(array(
        'secret' => 'q5jBZojDfaQFzPGyhmAEFgz6C5j3NsjJ', // your secret key
        'token' => $_POST['pc-token'],
        'clientUid' => hash('sha256', $_SERVER['REMOTE_ADDR']), // unique client id (same value as in the data-client-uid attribute)
        'name' => $_POST['username'] // field which was marked by 'data-pc-user' (optional)
    )));
    
    $response = json_decode(curl_exec($curl));
    curl_close($curl);

    if($response->success) {
        echo "Token was successfully verified.";
        // add your form logic
    } else {
        echo "Error: Token verfification failed.";
    }
} else {
    echo "Error: Token was missing in POST request.";
}
?>

Dokumentation der API-Schnittstelle für das Backend

API-Schnittstelle zur Token-Verifizierung

Nachdem du dein Formular abgesendet hast, muss das Token in deinem Backend verifiziert werden. Dazu übergibst du das Token und einige zusätzliche Parameter per JSON an unsere Verifiy-Schnittstelle, damit wir prüfen können, ob das Captcha korrekt gelöst wurde oder die alternative E-Mail-Authentisierung ein positives Ergebnis hatte. Die Verifiy-Schnittstelle wird über die folgende URL aufgerufen: https://api.power-captcha.com/pcu/v1/verifiy

Im Header muss beim Aufruf der Wert X-API-Key mit deinem API-Key gesetzt sein, und im Request Body muss das Token und die zusätzlichen Parameter als JSON per POST an unsere Schnittstelle übertragen werden.

Beispiel JSON für den Request:

				
					{
    "secret": "{secret-key}",
    "token": "{token}",
    "clientUid": "{client-uid}",
    "name": "{username}"
}

Füge deinen Secret-Key im Parameter “secret” ein. Deinen Secret-Key findest du in deiner Konto-Verwaltung. Der Parameter “token” enthält das Token, welches über unser JavaScript generiert wurde. Das Token befindet sich im POST/GET-Feld “pc-token”. Der Parameter “clientUid” muss dieselbe eindeutige Client-ID enthalten, die bereits im Formular vergeben wurde. Darüber wird geprüft, ob das Token ursprünglich für diese Client-ID erstellt wurde. Falls du im Frontend ein Feld mit “data-pc-user” markiert hast, musst du den Wert dieses Feldes in dem Parameter “name” an unsere Verifiy-Schnittstelle übergeben, um einen Benutzernamen / E-Mail-Adresse zu schützen.

Beispiel Rückgabewert:

				
					{
     "success": true,
     "errors": []
}

Wenn das Feld “success” mit “true” belegt ist, dann war die Verifizierung erfolgreich (Token ist gültig), und du kannst mit der Evaluierung deines Formulars fortfahren. Ist das Feld “success” mit “false” belegt, dann ist das Token entweder ungültig oder der Request ist falsch aufgebaut. In diesem Fall sollte die Evaluierung des Formulars umgehend abgebrochen werden, da das Token nicht von POWER CAPTCHA verifiziert werden konnte. Wenn der Request falsch aufgebaut ist, erscheint im Feld “errors” eine Liste mit den folgenden Fehler-Codes:

Fehler-Code	Beschreibung
missing_token	Beim Request wurde kein oder ein leeres Token mitgebeben.
missing_secret	Beim Request wurde kein Secret-Key mitgegeben.
invalid_secret	Der Secret-Key ist ungültig oder passt nicht zum API-Key.
invalid_token	Das Token ist ungültig.

DEMO-FORMULAR

Gib einen Testnamen ein und klicke auf die Sicherheitsprüfung um POWER CAPTCHA zu testen. Anschließend kannst du das Formular absenden.

POWER CAPTCHA DEMO

Jetzt testen

Mit unserer Demo kannst du die Anwendung auf deiner Website / App mit fiktiven Daten simulieren. Weitere Infos zur Demo sowie zusätzliche Testformulare findest du auf unserer Demo-Seite.

JETZT SCHÜTZEN

Starte jetzt mit POWER CAPTCHA

Du möchtest POWER CAPTCHA direkt verwenden? Dann hole dir hier eine Lizenz und folge unserer Schritt-für-Schritt-Anleitung.