logoDokumentation
Suchen

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.

image-20250427154654130

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.

image-20250427154749118

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.

image-20250427154933547

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:

  1. 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.
  2. 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);
              
              String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

            
Diesen Codeblock im schwebenden Fenster anzeigen
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" }
              
              {
    "lot_number": "f26d13345c9980c7705b9111b9398a0f",
    "captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
    "sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
    "pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
    "gen_time": "1684826917",
    "captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}

            
Diesen Codeblock im schwebenden Fenster anzeigen
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" } }
              
              {
    "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"
    }
}

            
Diesen Codeblock im schwebenden Fenster anzeigen

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(); } }
              
              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();

    }
}

            
Diesen Codeblock im schwebenden Fenster anzeigen
icon
Vertrieb kontaktieren