Serverzugriff
Produktkommunikationsprozess
Normaler Ablauf
Wenn der Verifizierungsdienst ordnungsgemäß funktioniert und das Netzwerk der Nutzer:innen stabil ist, läuft der Verifizierungsprozess wie gewohnt ab. Der Server muss sich dabei auf die Phase der Sekundärverifizierung konzentrieren.

Ausnahmeprozess
Offline-Prozess im Verifizierungscode integriert
Bei einer Störung des Verifizierungsdienstes und Nutzung des im Verifizierungscode integrierten Offline-Modus muss sich der Server ebenfalls auf die Phase der Sekundärverifizierung konzentrieren. In diesem Fall tritt beim Serveraufruf an den Verifizierungsdienst eine Ausnahme auf. Es wird empfohlen, diese Ausnahme abzufangen und je nach Geschäftsszenario zu entscheiden, ob der:die Nutzer:in fortfahren darf.

Individueller Downgrade-Prozess (nur als Referenz)
Bei einer Störung des Verifizierungsdienstes und Einsatz einer individuellen Downgrade-Verifizierung, wie z. B. einer Zeichenverifizierung, empfiehlt es sich, dass der Server eine Schnittstelle oder einen Schalter bereitstellt, damit das Frontend die jeweils verwendete Verifizierungsmethode bestimmen kann. Der Server kann die vom Verifizierungscode bereitgestellte Schnittstelle check_status nutzen, um zu prüfen, ob der Verifizierungscode ordnungsgemäß funktioniert.

Server-Integrationsplan für Verifizierungscodes
Vorbereitungen vor der Integration
Bitte beziehen Sie die erforderlichen Ressourcen von der Integrations-Clientseite. Informationen wie Domain-Adressen erhalten Sie nach Abschluss der Bereitstellung von Ihrer internen Firmenkontaktperson.
| Client-Typ | Erforderliche Ressourcen | Ressourcenbeschreibung |
| Server | captchaId | ID des Verifizierungsszenarios, kann über die Managementkonsole erstellt werden |
| captchaKey | KEY des Verifizierungsszenarios, wird beim Anlegen eines neuen Szenarios in der Managementkonsole generiert und entspricht eindeutig der captchaId |
Server-Integration
Nachdem der:die Nutzer:in die Verifizierung im Frontend abgeschlossen hat, werden eine Reihe von Parametern zum Verifizierungscode erzeugt. Die Anfrage des:der Nutzer:in an das Business-System enthält diese Parameter, die das Backend an die Sekundärverifizierungs-Schnittstelle von EngageLab übermittelt, um die Gültigkeit der Verifizierung zu bestätigen.
Am Beispiel eines Login-Szenarios:
- Vor der Integration des Verifizierungscodes sendet das Frontend Benutzername und Passwort an die Login-Schnittstelle des Business-Systems. Das System prüft, ob Benutzername und Passwort übereinstimmen. Stimmen sie überein, ist der Login erfolgreich; andernfalls wird der Login verweigert.
- Nach der Integration des Verifizierungscodes sendet das Frontend sowohl Geschäftsdaten als auch verifizierungsbezogene Parameter an die Login-Schnittstelle. Das Backend übermittelt die verifizierungsbezogenen Parameter an die validate-Schnittstelle des Verifizierungsservers, um das Ergebnis der Sekundärverifizierung zu erhalten. Basierend auf dem Verifizierungsergebnis sowie dem Abgleich von Benutzername und Passwort entscheidet das System, ob der:die Nutzer:in mit den weiteren Geschäftsprozessen fortfahren darf.
Beschreibung der validate-Schnittstelle
| Schnittstelleninformation | Beschreibung |
|---|---|
| Schnittstellenadresse | https://captcha-api.engagelab.com/validate |
| Anfragemethode | POST |
| Anfrageformat | application/json |
| Antworttyp | json |
Anfrageparameter
| Parametername | Typ | Beschreibung | Quelle |
|---|---|---|---|
| lot_number | string | Server-Verifizierungs-Seriennummer | Vom Frontend übergeben |
| captcha_output | string | Verifizierungsausgabe | Vom Frontend übergeben |
| pass_token | string | Verifizierungs-Pass-Token | Vom Frontend übergeben |
| gen_time | string | Zeitstempel der Verifizierung | Vom Frontend übergeben |
| captcha_id | string | Verifizierungsszenario-ID | Geschäftskonfigurationsdatei, muss mit captchaId im Frontend übereinstimmen |
| sign_token | string | Verifizierungssignatur | Vom Business-System generiert |
Der sign_token wird wie folgt generiert:
Verwenden Sie die aktuelle Verifizierungs-Seriennummer lot_number des:der Nutzer:in als Originalnachricht, den captchaKey des Kunden als Schlüssel und den HMAC_SHA256-Hashalgorithmus, um daraus eine Einweg-Signatur zu erzeugen.
Ein Beispiel in Java:
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
Beispiel für den Anfrage-Body
{
"lot_number": "f26d13345c9980c7705b9111b9398a0f",
"captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
"sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
"pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
"gen_time": "1684826917",
"captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}
Antwortparameter
| Parametername | Typ | Erforderlich | Beispiel | Beschreibung |
|---|---|---|---|---|
| status | String | Ja | success | Status der Schnittstellenantwort, „success“ bedeutet erfolgreiche Antwort |
| data | Object | Ja | Siehe unten | Rückgabefeld bei erfolgreicher Schnittstellenantwort |
Das data-Feld enthält folgende Parameter:
| Parametername | Typ | Erforderlich | Beispiel | Beschreibung |
|---|---|---|---|---|
| result | String | Ja | success | Ergebnis der Sekundärverifizierung, success bedeutet Verifizierung bestanden, andere Werte bedeuten Verifizierung fehlgeschlagen |
| reason | String | Ja | "" | Beschreibung des Verifizierungsergebnisses |
| captcha_args | Object | Ja | {} | Informationen für den Client, enthält vor allem Strategieergebnisse |
Der Nachweis für eine bestandene Verifizierung ist: Das Feld status in der Antwort ist „success“ und das Feld result ist ebenfalls „success“.
Die im captcha_args enthaltenen Parameter sind:
| Parametername | Typ | Erforderlich | Beispiel | Beschreibung |
|---|---|---|---|---|
| model_cnn | int | Ja | 0 | Ergebnis der CNN-Sliding-Track-Erkennung, 0 = normal, 1 = abnormale Spur |
| model_probability | int | Ja | 0 | Gibt an, ob es sich um eine Captcha-Plattformanfrage handelt, 0 = normale Nutzer:innen, 1 = Captcha-Anfragen, Empfehlung: Echtzeitbehandlung durch das Business-System |
| used_type | String | Ja | slide | Verwendete Verifizierungsmethode |
| web_simulator | int | Ja | 0 | Gibt an, ob ein Simulator verwendet wurde, 0 = normaler Browser, 1 = Simulator |
| user_ip | String | Ja | "127.0.0.1" | Nutzer:innen-IP bei bestandener Verifizierung |
| user_referer | String | Ja | "" | Referer der Nutzer:innen-Anfrage bei bestandener Verifizierung |
| cnn_records | int | Ja | 0 | Einzelne abnormale Spur während des gesamten Prozesses erkannt |
| user_agent | String | Ja | "User-Agent" | User-Agent bei bestandener Verifizierung |
| lot_number | String | Ja | "9b57c5289e" | Verifizierungs-Seriennummer der Nutzer:innen |
Hinweis: model_probability ist der Captcha-Identifier. Wenn dieser Wert 1 ist, handelt es sich um eine abnormale Captcha-Anfrage. Es wird empfohlen, dies im Business-System nachzubehandeln.
Wenn das Feld result in data „success“ ist, wurde die Verifizierung bestanden.
Beispiel für eine Antwort
{
"status": "success",
"data": {
"captcha_args": {
"cnn_records": 0,
"lot_number": "a989b864ad08cc08f270c22d9ab1fba0",
"model_cnn": 0,
"model_probability": 0,
"used_type": "slide",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, wie Gecko) Chrome/135.0.0.0 Safari/537.36",
"user_ip": "59.174.224.96",
"user_referer": "http://127.0.0.1:5000/",
"web_simulator": 0
},
"reason": "validate success",
"result": "success"
}
}
Beispiel für Java-Code-Integration
Am Beispiel einer Business-Implementierung in Java finden Sie hier einen Beispielcode:
package com.engagelab.demo.controller;
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
import org.json.JSONObject;
import org.springframework.http.*;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;
import java.util.HashMap;
import java.util.Map;
@RestController
public class MainController {
@RequestMapping(value = "/login", method = {RequestMethod.GET})
public String userLogin(@RequestParam Map<String, String> getParams) {
// 1. Initialisierung der Parameter, muss mit captchaId im Frontend übereinstimmen oder kann in der Konfigurationsdatei hinterlegt werden
String captchaId = "37830cbb24f5a2134d39c7cf3093bc14";
String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec";
// domain ist die Domain des EngageLab-Verifizierungsdienstes
String domain = "https://captcha-api.engagelab.com";
// 2. Verifizierungs-Seriennummer und weitere Parameter, die nach der Nutzer:innen-Verifizierung vom Frontend übergeben werden
String lotNumber = getParams.get("lot_number");
String captchaOutput = getParams.get("captcha_output");
String passToken = getParams.get("pass_token");
String genTime = getParams.get("gen_time");
// 3. Signatur erzeugen
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
// 4. Verifizierungsparameter an die Sekundärverifizierungs-Schnittstelle senden, um den Verifizierungsstatus zu prüfen
Map<String, String> queryParams = new HashMap<>();
queryParams.put("captcha_id", captchaId);
queryParams.put("lot_number", lotNumber);
queryParams.put("captcha_output", captchaOutput);
queryParams.put("pass_token", passToken);
queryParams.put("gen_time", genTime);
queryParams.put("sign_token", signToken);
String url = String.format(domain + "/validate");
SimpleClientHttpRequestFactory clientHttpRequestFactory = new SimpleClientHttpRequestFactory();
clientHttpRequestFactory.setConnectTimeout(3000); // Verbindungs-Timeout setzen
clientHttpRequestFactory.setReadTimeout(1500); // Lese-Timeout setzen
RestTemplate client = new RestTemplate();
client.setRequestFactory(clientHttpRequestFactory);
JSONObject responseJsonObject = new JSONObject();
try {
RequestEntity<Map<String, String>> requestEntity = RequestEntity.post(url).accept(MediaType.APPLICATION_JSON).body(queryParams);
ResponseEntity<String> response = client.exchange(requestEntity, String.class);
String resBody = response.getBody();
responseJsonObject = new JSONObject(resBody);
}catch (Exception e){
responseJsonObject.put("status", "success");
responseJsonObject.put("data", new JSONObject("{\"result\": \"success\", \"reason\": \"request captcha api fail\"}"));
}
JSONObject res = new JSONObject();
String status = responseJsonObject.getString("status");
if (status.equals("success")) {
String data = responseJsonObject.getJSONObject("data").getString("result");
if (data.equals("success")) {
res.put("login", "success");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
} else {
res.put("login", "fail");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
}
JSONObject captchaArgs = responseJsonObject.getJSONObject("data").getJSONObject("captcha_args");
Integer model_probability = captchaArgs.getInt("model_probability");
System.out.println("Das Captcha-Erkennungsergebnis lautet: " + model_probability);
} else {
res.put("login", "fail");
res.put("reason", "captcha verify fail");
}
return res.toString();
}
}

