logoDocumentation
Rechercher

Accès serveur

Processus de communication produit

Processus normal

Lorsque le service de vérification fonctionne normalement et que le réseau de l'utilisateur se charge correctement, le processus de code de vérification se déroule. Le serveur doit se concentrer sur la phase de seconde vérification.

image-20250427154654130

Processus d'exception

Processus hors ligne intégré au code de vérification

Lorsque le service de vérification est anormal et que le mode hors ligne intégré au code de vérification est utilisé, le serveur doit se concentrer sur la phase de seconde vérification. Dans ce cas, la requête du serveur vers le service de code de vérification rencontrera une exception. Il est recommandé de capturer l'exception et de déterminer s'il faut autoriser l'utilisateur à poursuivre en fonction du scénario métier.

image-20250427154749118

Processus de dégradation personnalisé (à titre de référence uniquement)

Lorsque le service de vérification est anormal et qu'une vérification de dégradation personnalisée, telle qu'une vérification de caractères, est utilisée, il est recommandé que le serveur ajoute une interface ou un commutateur pour que le frontend puisse déterminer la méthode de vérification spécifique. Le serveur peut utiliser l'interface check_status fournie par le code de vérification pour déterminer si le code de vérification fonctionne normalement.

image-20250427154933547

Plan d'intégration du code de vérification côté serveur

Préparatifs avant intégration

Veuillez obtenir les ressources nécessaires du côté client d'intégration. Les informations telles que les adresses de domaine doivent être obtenues auprès du contact interne de l'entreprise une fois le déploiement terminé.

Type de client Ressources requises Description de la ressource
Serveur captchaId ID du scénario de vérification, peut être créé via la console de gestion
captchaKey Clé du scénario de vérification, générée lors de la création d'un nouveau scénario dans la console de gestion, correspond un-à-un avec captchaId

Intégration serveur

Après que l'utilisateur a terminé la vérification sur l'interface frontend, un ensemble de paramètres liés au code de vérification sera généré. La requête métier de l'utilisateur transporte ces paramètres, et l'interface métier backend télécharge ces paramètres vers l'interface de seconde vérification EngageLab pour confirmer la validité de la vérification de l'utilisateur.

En prenant l'exemple du scénario de connexion :

  1. Avant d'intégrer le code de vérification, le frontend transmet le nom d'utilisateur et le mot de passe pour demander l'interface de connexion métier. Le côté métier détermine si le nom d'utilisateur et le mot de passe correspondent. S'ils correspondent, la connexion réussit ; sinon, la connexion est refusée.
  2. Après l'intégration du code de vérification, le frontend transmet les informations métier et les paramètres liés au code de vérification pour demander l'interface de connexion métier. Le côté métier transmet les paramètres liés au code de vérification pour demander l'interface de seconde vérification (validate) du serveur de code de vérification afin d'obtenir le résultat de la vérification. En fonction du résultat de la vérification et du résultat de correspondance du nom d'utilisateur et du mot de passe, il détermine s'il faut autoriser l'utilisateur à poursuivre les processus métier suivants.

Description de l'interface validate

Informations de l'interface Description
Adresse de l'interface https://captcha-api.engagelab.com/validate
Méthode de requête POST
Format de requête application/json
Type de réponse json
Paramètres de la requête
Nom du paramètre Type Description Source
lot_number string Numéro de série de vérification serveur Transmis depuis le frontend
captcha_output string Informations de sortie de vérification Transmis depuis le frontend
pass_token string Jeton de passage de la vérification Transmis depuis le frontend
gen_time string Horodatage de passage de la vérification Transmis depuis le frontend
captcha_id string ID du scénario de vérification Fichier de configuration métier, doit correspondre au captchaId utilisé par le frontend
sign_token string Signature de vérification Générée par le côté métier

Le sign_token est généré comme suit :

Utilisez le numéro de série de vérification actuel de l'utilisateur lot_number comme message d'origine, la clé privée de vérification du client captchaKey comme clé, et utilisez l'algorithme de hachage hmac_sha256 pour hacher le message et la clé en sens unique afin de générer la signature finale.

Un exemple en code Java est le suivant :

String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
              
              String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

            
Afficher ce bloc de code dans la fenêtre flottante
Exemple de corps de requête
{ "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"
}

            
Afficher ce bloc de code dans la fenêtre flottante
Paramètres de la réponse
Nom du paramètre Type Obligatoire Exemple Description
status String Oui success Statut de la réponse de l'interface, success indique une réponse réussie
data Object Oui Voir description du champ data Champ retourné lorsque l'interface répond avec succès

Le champ data est décrit comme suit :

Nom du paramètre Type Obligatoire Exemple Description
result String Oui success Résultat de la seconde vérification, success indique que la vérification est réussie, toute autre valeur indique un échec
reason String Oui "" Description du résultat de la vérification
captcha_args Object Oui {} Informations retournées au client, incluant principalement certains résultats de stratégie

L'identifiant de passage de la vérification est : le champ status dans la réponse est success, et le champ result est également success

Les paramètres inclus dans captcha_args sont les suivants :

Nom du paramètre Type Obligatoire Exemple Description
model_cnn int Oui 0 Résultat du modèle de trajectoire glissante CNN, 0 indique une trajectoire normale, 1 indique une trajectoire anormale
model_probability int Oui 0 S'il s'agit d'une requête de plateforme captcha, 0 pour les utilisateurs normaux, 1 pour les requêtes captcha, il est recommandé de le traiter en temps réel
used_type String Oui slide Méthode de vérification utilisée cette fois
web_simulator int Oui 0 S'il s'agit d'un simulateur, 0 indique un navigateur normal, 1 indique un simulateur
user_ip String Oui "127.0.0.1" IP utilisateur lors du passage de la vérification
user_referer String Oui "" Referer de la requête utilisateur lors du passage de la vérification
cnn_records int Oui 0 S'il y a eu une prédiction unique d'une trajectoire anormale pendant tout le processus
user_agent String Oui "User-Agent" UA utilisateur lors du passage de la vérification
lot_number String Oui "9b57c5289e" Numéro de série de vérification utilisateur

Remarque : model_probability est l'identifiant captcha. Lorsque cet identifiant vaut 1, il est reconnu comme une requête captcha anormale. Il est recommandé de le traiter ultérieurement côté métier.

Lorsque le champ result dans data est success, cela indique que le résultat de la vérification est validé

Exemple de réponse
{ "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, like 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, like 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"
    }
}

            
Afficher ce bloc de code dans la fenêtre flottante

Exemple d'intégration en Java

En prenant l'exemple d'un développement côté métier en langage Java, le code de référence est le suivant :

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. Initialiser les informations de paramètre, doit être cohérent avec le captchaId utilisé par le frontend, ou peut être placé dans le fichier de configuration String captchaId = "37830cbb24f5a2134d39c7cf3093bc14"; String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec"; // domain est le nom de domaine du service de code de vérification EngageLab String domain = "https://captcha-api.engagelab.com"; // 2. Récupérer le numéro de série de vérification et autres paramètres transmis depuis le frontend après la vérification utilisateur 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. Générer la signature String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber); // 4. Télécharger les paramètres de vérification à l'interface de seconde vérification pour valider le statut de vérification utilisateur 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); // Définir le délai de connexion clientHttpRequestFactory.setReadTimeout(1500); // Définir le délai de lecture 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("Le résultat de reconnaissance captcha est : " + model_probability); } else { res.put("login", "fail"); res.put("reason", "échec de la vérification captcha"); } 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. Initialiser les informations de paramètre, doit être cohérent avec le captchaId utilisé par le frontend, ou peut être placé dans le fichier de configuration
        String captchaId = "37830cbb24f5a2134d39c7cf3093bc14";
        String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec";
        // domain est le nom de domaine du service de code de vérification EngageLab
        String domain = "https://captcha-api.engagelab.com";

        // 2. Récupérer le numéro de série de vérification et autres paramètres transmis depuis le frontend après la vérification utilisateur
        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. Générer la signature
        String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

        // 4. Télécharger les paramètres de vérification à l'interface de seconde vérification pour valider le statut de vérification utilisateur
        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);  // Définir le délai de connexion
        clientHttpRequestFactory.setReadTimeout(1500);  // Définir le délai de lecture
        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("Le résultat de reconnaissance captcha est : " + model_probability);
        } else {
            res.put("login", "fail");
            res.put("reason", "échec de la vérification captcha");
        }
        return res.toString();

    }
}

            
Afficher ce bloc de code dans la fenêtre flottante
icon
Contactez-nous