Technische Details des Backends

Nachfolgend wird erläutert, wie Sie serverseitig das Verifikationsergebnis abrufen und darauf basierend die nächsten Schritte festlegen.

Unterstützte Technologien

Sie können Trustcaptcha grundsätzlich mit jeder beliebigen Programmiersprache und Framework ihrer Wahl verwenden und ganz individuell für ihre Bedürfnisse anzupassen. Dafür finden Sie nachstehend eine ausführliche Dokumentation des Backend-Prozesses sowie der dazugehörigen API-Schnittstelle.

Unterstützung durch Bibliotheken

Um Ihnen die Verwendung von Trustcaptcha so einfach wie möglich zu machen, können Sie unsere Bibliotheken für die beliebtesten Programmiersprachen und Frameworks verwenden. Eine Anleitung zur Integration finden Sie hier.

Folgende Technologien werden aktuell von uns direkt unterstützt:

Typescript

NodeJS

Python

Java

Kotlin

Spring

PHP

Ruby

.NET

Rust

Groovy

Scala

Der Verifikationstoken

Wenn ein Captcha erfolgreich gelöst wird, gibt die Trustcaptcha-Komponente am Ende einen Verifikationstoken zurück. Dieser muss an das Backend übermittelt werden und kann da weiterverarbeitet werden. Nachstehend wird der Aufbau des Verifikationstokens erklärt.

Base64 kodiert

Der von der Trustcaptcha-Komponente zurückgegebene Verifikationstoken ist mit Base64 kodiert.

Base64 dekodiert

Wenn Sie den Verifikationstoken dekodieren, erhalten Sie ein JSON-Objekt zurück. Dieser enthält die Verifikation-ID und den verschlüsselten Zugangstoken namens encryptedAccessToken.

Schlüssel	Wert	Beschreibung
verificationId	UUID	Eindeutige Kennung (ID) der Überprüfung.
encryptedAccessToken	Text	Verschlüsselter Zugriffstoken zum Abrufen des Überprüfungsergebnisses.

Entschlüsseln des Zugangstokens

Das Zugangstoken namens encryptedAccessToken im Verifikationsergebnis ist mit AES verschlüsselt. Das stellt sicher, dass nur Sie in der Lage sind, das Verifikationsergebnis abzurufen. Zuerst muss das encryptedAccessToken mit base64 dekodiert und in ein Binärformat umgewandelt werden. Entschlüsseln Sie es anschließend mit Hilfe Ihres secret-key. Verwenden Sie AES-265 im CBC-Modus. Setzen Sie ein PKCS5Padding und einen 16-Byte-Initialisierungsvektor (IV) ein.

Implementierungsbeispiel

Nachstehend finden Sie einige Implementationsbeispiele für die AES-Entschlüsselung.

Das Verifikationsergebnis

Nachstehend wird Ihnen erklärt, wie Sie das Verifikationsergebnis abrufen können, welche Informationen es beinhaltet und wie Sie damit arbeiten können.

Ergebnis abrufen

Über folgende URL können Sie das Verifikationsergebnis von unseren Servern abrufen.

Parameter	Typ	Beschreibung
verificationId	Pfad	Eindeutige Kennung (ID) der Überprüfung.
decryptedAccessToken	Abfrage	Entschlüsselter Zugriffstoken zum Abrufen des Überprüfungsergebnisses.

Bitte beachten Sie, dass der Verifikationstoken nach 30 Minuten ungültig wird und das Verifikationsergebnis nur ein einziges Mal abgerufen werden kann.

Ergebnis verarbeiten

Das zurückgelieferte Verifikationsergebnis sieht wie folgt aus:

Parameter	Value	Description
captchaId	UUID	Eindeutige Kennung (ID) des jeweiligen CAPTCHA.
verificationId	UUID	Eindeutige Kennung (ID) der Überprüfung.
verificationPassed	Boolean	Aussage darüber, ob das CAPTCHA grundsätzlich bestanden wurde oder nicht.
score	Zahl	Wahrscheinlichkeitsstufe, dass der Client ein Bot ist.
reason	Text	Begründung für die Berechnung von verificationPassed und score.
mode	Text	Ausgewählter CAPTCHA-Modus.
origin	Text	Die Seite, auf der das CAPTCHA gelöst wurde.
ipAddress	Text	IP-Adresse (IPv4 oder IPv6) des Clients.
deviceFamily	Text	Name der Gerätefamilie, die vom Client verwendet wird.
operatingSystem	Text	Name und Version des vom Client verwendeten Betriebssystems.
browser	Text	Name und Version des vom Client verwendeten Browsers.
creationTimestamp	Zeitstempel (UTC)	Der Moment, in dem der Überprüfungsprozess (das CAPTCHA) vom Client gestartet wurde.
releaseTimestamp	Zeitstempel (UTC)	Der Moment, in dem der Überprüfungsprozess (das CAPTCHA) vom Client abgeschlossen wurde.
retrievalTimestamp	Zeitstempel (UTC)	Der Moment, in dem das Überprüfungsergebnis vom Website-Betreiber abgerufen wurde.

Der Bot-Score

Der Bot-Score liefert eine Dezimalzahl zwischen 0 und 1. Er gibt Auskunft darüber, wie hoch die Wahrscheinlichkeit ist, dass der anfragende Client ein Bot ist. Je niedriger der Wert, desto wahrscheinlicher ist es, dass es sich um einen menschlichen Benutzer handelt. Je höher der Wert, desto wahrscheinlicher handelt es sich um einen maschinellen Nutzer.

Der Bot-Score ermöglicht Ihnen, einen einfachen Schwellenwert zu definieren, bei dem Sie die Anfrage entweder zulassen oder ablehnen. Unsere Empfehlung liegt bei einem Schwellwert von 0.5. Sie können jedoch auch, basierend auf dem Bot-Score, für verschiedene Wahrscheinlichkeiten unterschiedliche weitere Sicherheitsmaßnahmen festlegen, wie beispielsweise eine zusätzliche 2-Faktor-Authentifizierung oder eine Bestätigung per E-Mail.

Die Begründung

Der Grund gibt Aufschluss darüber, warum der Bot-Score und die Aussage über das VerificationPassed entsprechend getroffen wurde.

Grund	VerificationPassed	Score	Beschreibung
BYPASS_KEY	true	0	Das CAPTCHA wurde mit einem Bypass-Token gelöst.
CUSTOM_ALLOW_LIST	true	0	Die IP-Adresse des Clients befindet sich auf der benutzerdefinierten Erlaubnisliste.
CUSTOM_BLOCK_LIST	false	1	Die IP-Adresse des Clients befindet sich auf der benutzerdefinierten Sperrliste.
GLOBAL_ALLOW_LIST	true	0	Die IP-Adresse des Clients befindet sich auf der globalen Erlaubnisliste von Trustcaptcha.
GLOBAL_BLOCK_LIST	false	1	Die IP-Adresse des Clients befindet sich auf der globalen Sperrliste von Trustcaptcha.
GEOBLOCKING	false	1	Die Region des Clients ist auf der Länderliste blockiert.
REQUEST_REJECTED	false	1	Der Überprüfungsversuch wurde von Trustcaptcha abgelehnt.
ONLY_PROOF_OF_WORK	true	0	Überprüfung ohne Bot-Score bestanden (z.B. Minimaldatenmodus).
CALCULATED	true	Individual	Der Bot-Score wurde basierend auf Datenanalyse berechnet.
CHALLENGES_NOT_SOLVED_CORRECTLY	false	1	Der Client hat die Proof-of-Work-Herausforderungen nicht korrekt gelöst.
CHALLENGES_NOT_SOLVED_IN_SPECIFIED_TIME	false	1	Der Client hat die Proof-of-Work-Herausforderungen nicht innerhalb der angegebenen Zeit eingereicht.

Fehlerbehandlung

Beim Abrufen des Verifikationsergebnisses können Fehler auftreten. Nachstehend finden Sie eine Übersicht aller Status-Codes samt einer Beschreibung, was schief gelaufen ist und was Sie beachten sollten.

Statuscode	Statusname	Beschreibung
400	Ungültige Anfrage	Die Anfrage wurde unter falschen Annahmen gestellt. Möglicherweise ist die Verifizierungs-ID (verificationId) keine UUID oder das Zugriffstoken (accessToken) entspricht nicht dem angegebenen Format.
403	Verboten	Das Zugriffstoken (accessToken) ist nicht gültig. Bitte überprüfen Sie das Zugriffstoken.
404	Nicht gefunden	Die Verifizierung existiert nicht. Bitte überprüfen Sie die Verifizierungs-ID. Es ist auch möglich, dass die Verifizierung bereits abgerufen und nun gelöscht wurde.
410	Nicht mehr verfügbar	Das Verifizierungsergebnis wurde entweder bereits abgerufen oder wird nicht mehr bereitgestellt, da der Verifizierungsversuch zu alt ist. Denken Sie daran, dass Sie das Verifizierungsergebnis nur einmal, kurz nach der Verifizierung, abrufen können.
423	Gesperrt	Das Verifizierungsergebnis wurde noch nicht freigegeben. Bitte warten Sie, bis die Verifizierung abgeschlossen ist.
422	Unverarbeitbarer Inhalt	Der eingestellte CAPTCHA-Modus der Trustcaptcha-Komponente stimmt nicht mit dem in den CAPTCHA-Einstellungen eingestellten Modus überein.
500	Interner Serverfehler	Es ist ein interner Serverfehler aufgetreten. Wenn dies wiederholt auftritt und über einen längeren Zeitraum anhält, wenden Sie sich bitte an den Support.