HTML und Django

Dieses Beispiel schützt das Kontaktformular einer bestehenden Anwendung ohne Frontend-Framework. Die Seite wird als Django-Template ausgeliefert, das Formular sendet einen gewöhnlichen POST. Das Widget legt dabei selbst das versteckte Feld eu-captcha-response an, das mit dem Formular mitgeht.

Note

In einer Single-Page-Anwendung nehmen Sie das Token stattdessen über einen Callback entgegen und senden es als JSON. Siehe React und PHP.

Voraussetzungen

Die folgenden Voraussetzungen müssen erfüllt sein:

Voraussetzung	Wert
Django-Projekt	läuft und liefert die Seite aus
Python	Version 3 mit pip
Sitekey	Öffentlicher Sitekey und Secret aus der Ansicht Details

Warning

Der öffentliche Sitekey gehört in die Seite, das Secret ausschließlich auf den Server. Ein Secret in einem Template liest jeder Besucher mit.

Projektstruktur

Die folgenden Dateien ändern sich. Alles Übrige im Projekt bleibt unverändert:

mein-projekt/                     # bestehendes Django-Projekt
├── manage.py
├── templates/
│   └── kontakt.html              # ← Schritt 1 und 2: Skript und Widget einbinden
└── server/
    ├── settings.py               # ← Schritt 3: App und Zugangsdaten eintragen
    ├── urls.py                   # ← Schritt 3: Route /kontakt/ registrieren
    └── views.py                  # ← Schritt 3: Prüfung an den Anfang der View setzen

Schritt 1: Widget einbinden

Die Seite steht in der Datei templates/kontakt.html.

Laden Sie das Skript verify.js vom Myra-CDN und setzen Sie das Widget-Element in das Formular:

<script src="https://cdn.eu-captcha.eu/verify.js" async defer></script>

<form action="/kontakt/" method="post">
  <input name="email" type="email" required />
  <textarea name="message" required></textarea>

  <div class="eu-captcha" data-sitekey="EUCAPTCHA_SITE_KEY"></div>

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

Das Skript legt den versteckten iframe an, startet die Challenge selbsttätig und fügt das versteckte Feld eu-captcha-response in das Formular ein. Das Feld geht beim Absenden mit.

Schritt 2: Absenden freigeben

Falls erforderlich, sperren Sie die Schaltfläche und geben sie erst nach der Challenge frei. Werten Sie dazu die Fensternachricht euCaptchaCompleted aus. Prüfen Sie dabei den Ursprung der Nachricht, da jedes Skript und jede Erweiterung im Browser Nachrichten senden kann:

<script>
  const CAPTCHA_ORIGIN = "https://cdn.eu-captcha.eu";
  const btn = document.querySelector('button[type="submit"]');
  btn.disabled = true;

  window.addEventListener("message", (msg) => {
    if (msg.origin !== CAPTCHA_ORIGIN) return;
    const data = msg.data ?? {};
    if (data.type === "euCaptchaCompleted") {
      btn.disabled = false;
    }
  });
</script>

Warning

Die Sperre im Browser steuert nur die Bedienung. Die Prüfung des Tokens auf dem Server bleibt in jedem Fall erforderlich.

Schritt 3: Token prüfen

Die Prüfung gehört in die View, die den POST des Formulars entgegennimmt, hier die Route /kontakt/ in der Datei server/views.py. Sie steht an erster Stelle, vor jeder Verarbeitung.

Installieren Sie die App:

pip install myra-eucaptcha-django

Tragen Sie die App und die Zugangsdaten in die Datei settings.py ein:

import os

INSTALLED_APPS = [
    # ...
    "myra_eucaptcha_django",
]

EUCAPTCHA_SITEKEY = os.environ["EUCAPTCHA_SITE_KEY"]
EUCAPTCHA_SECRET = os.environ["EUCAPTCHA_SECRET_KEY"]

Legen Sie die Tabellen der App an:

python manage.py migrate

Setzen Sie die Prüfung an den Anfang der View:

from django.core.exceptions import ValidationError
from django.http import HttpResponse, HttpResponseBadRequest
from myra_eucaptcha_django import validate_captcha


def kontakt(request):
    if request.method == "POST":
        # Prüfung vor jeder Verarbeitung
        try:
            validate_captcha(
                token=request.POST.get("eu-captcha-response", ""),
                remote_addr=request.META.get("REMOTE_ADDR"),
            )
        except ValidationError:
            return HttpResponseBadRequest("captcha verification failed")

        # ab hier die bisherige Logik
        email = request.POST["email"]
        message = request.POST["message"]
        return HttpResponse("Danke!")

Note

Das Widget legt das Token als Formularfeld ab, deshalb steht es in request.POST. Halten Sie Sitekey und Secret in Umgebungsvariablen. Alternativ pflegen Sie die Zugangsdaten im Administrationsbereich von Django unter Captcha Configurations. Die als Vorgabe markierte Konfiguration hat Vorrang vor den Werten aus settings.py.

Warning

Im Trainingsmodus wirft validate_captcha keine ValidationError, und die Übermittlung läuft durch. Der Trainingsmodus greift bei einem unbekannten Sitekey, bei einem falschen Secret und bei abgeschaltetem Schutz. Prüfen Sie deshalb immer mit den echten Zugangsdaten aus dem Kundenportal.

Siehe Django.

Integration prüfen

Ansicht Integration Test mit dem Ergebnis Fully Integrated

Prüfen Sie zum Schluss in der Ansicht Integration Test des Sitekeys, ob Frontend und Backend zusammenspielen. Danach trägt der Sitekey den Status Fully Integrated.

Siehe Integration testen.