การรวมกับบริการ

              
              # サーバーアクセスドキュメント

## 製品通信プロセス

### 通常プロセス

認証サービスが正常に動作し、ユーザーのネットワークが正常に読み込まれる場合、認証コードプロセスが進行します。サーバーは二次認証フェーズに注力する必要があります。

![image-20250427154654130](https://res.engagelab.net/docs/20251107/110348959/image-20250427154654130.png)

### 異常プロセス

#### 認証コードに組み込まれたオフラインプロセス

認証サービスが異常で、認証コードに組み込まれたオフラインモードが使用される場合、サーバーは二次認証フェーズに注力する必要があります。この場合、サーバーが認証コードサービスにリクエストを送信すると例外が発生します。例外をキャプチャし、ビジネスシナリオに基づいてユーザーの進行を許可するかどうかを判断することをお勧めします。

![image-20250427154749118](https://res.engagelab.net/docs/20251107/110348959/image-20250427154749118.png)

#### カスタムダウングレードプロセス（参考用）

認証サービスが異常で、文字認証などのカスタムダウングレード認証が使用される場合、サーバーはフロントエンドが特定の認証方法を判断するためのインターフェースまたはスイッチを追加することをお勧めします。サーバーは、認証コードが正常に動作しているかどうかを判断するために、認証コードが提供するcheck_statusインターフェースを使用できます。

![image-20250427154933547](https://res.engagelab.net/docs/20251107/125216354/./image-20250427154933547.png)

## サーバー認証コード統合プラン

### 統合前の準備

統合クライアント側から必要なリソースを取得してください。ドメインアドレスなどの情報は、デプロイメントが完了した後に社内の担当者から取得してください。

<table>
   <tr>
      <td>クライアントタイプ</td>
      <td>必要なリソース</td>
      <td>リソースの説明</td>
   </tr>
    <td rowspan="2">サーバー</td>
         <td>captchaId</td>
     <td>認証シナリオID、管理コンソールで作成可能</td>
    </tr>
    <tr>
        <td>captchaKey</td>
        <td>認証シナリオKEY、新しいシナリオを管理コンソールで作成する際に生成され、captchaIdと1対1で対応</td>
    </tr>
</table>

### サーバー統合

ユーザーがフロントエンドインターフェースで認証を完了すると、認証コードに関連する一連のパラメータが生成されます。ユーザーのビジネスリクエストはこれらのパラメータを含み、バックエンドビジネスインターフェースはこれらのパラメータをEngageLabの二次認証インターフェースにアップロードして、ユーザー認証の有効性を確認します。

ログインシナリオを例に取ると：

1. 認証コードを統合する前は、フロントエンドがユーザー名とパスワードを持ってビジネスログインインターフェースにリクエストを送信します。ビジネス側は、ユーザー名とパスワードが一致するかどうかを判断します。一致すればログイン成功、一致しなければログイン拒否となります。
2. 認証コードを統合した後は、フロントエンドがビジネス情報と**認証コード関連パラメータ**を持ってビジネスログインインターフェースにリクエストを送信します。ビジネス側は認証コード関連パラメータを持って認証コードサーバーの二次認証（validate）インターフェースにリクエストを送り、認証結果を取得します。認証結果とユーザー名とパスワードの一致結果に基づいて、ユーザーがその後のビジネスプロセスを進行できるかどうかを判断します。

#### validateインターフェースの説明

| インターフェース情報 | 説明         |
| -------------------- | ------------ |
| インターフェースアドレス | https://captcha-api.engagelab.com/validate |
| リクエストメソッド   | POST         |
| リクエスト形式       | application/json |
| レスポンスタイプ     | json         |

##### リクエストパラメータ

| パラメータ名        | 型     | 説明                    | 出所                                           |
| ------------------- | ------ | ----------------------- | --------------------------------------------- |
| lot_number          | string | サーバー認証シリアル番号 | フロントエンドから渡される                   |
| captcha_output      | string | 認証出力情報            | フロントエンドから渡される                   |
| pass_token          | string | 認証パストークン        | フロントエンドから渡される                   |
| gen_time            | string | 認証パスタイムスタンプ  | フロントエンドから渡される                   |
| captcha_id          | string | 認証シナリオID          | ビジネス設定ファイル、フロントエンドで使用するcaptchaIdと一致する必要あり |
| sign_token          | string | 認証署名                | ビジネス側で生成                              |

sign_tokenは以下のように生成されます：

ユーザーの現在の認証シリアル番号lot_numberを元のメッセージとして使用し、顧客の認証プライベートキーcaptchaKeyをキーとして使用し、hmac_sha256ハッシュアルゴリズムを使用してメッセージとキーを一方向でハッシュして最終署名を生成します。

Javaコードでの例は以下の通りです：

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

            

              
              {
    "lot_number": "f26d13345c9980c7705b9111b9398a0f",
    "captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
    "sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
    "pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
    "gen_time": "1684826917",
    "captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}

            

              
              {
    "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"
    }
}

            

              
              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. パラメータ情報を初期化、フロントエンドで使用するcaptchaIdと一致する必要があり、または設定ファイルに配置可能
        String captchaId = "37830cbb24f5a2134d39c7cf3093bc14";
        String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec";
        // domainはEngageLab認証コードサービスのドメイン名
        String domain = "https://captcha-api.engagelab.com";

        // 2. ユーザー認証後にフロントエンドから渡される認証シリアル番号およびその他のパラメータを取得
        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. 署名を生成
        String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

        // 4. 認証パラメータを二次認証インターフェースにアップロードして、ユーザー認証ステータスを検証
        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);  // 接続タイムアウトを設定
        clientHttpRequestFactory.setReadTimeout(1500);  // 読み取りタイムアウトを設定
        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("認証結果は: " + model_probability);
        } else {
            res.put("login", "fail");
            res.put("reason", "captcha verify fail");
        }
        return res.toString();

    }
}