> For the complete documentation index, see [llms.txt](https://docs.contiple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contiple.com/jp/api/open-api/post.md). # 会員認証 (POST) *** ## **➊** 会員認証 ### **1-1.** 概要 {% hint style="info" %} **会員認証とは？** 自社で利用中のサービスの会員認証をContipleのヘルプセンターに連携し、\ お客様がログインした状態でお問い合わせを送信し、送信したお問い合わせ内容を確認できるようにする機能です。 {% endhint %} * 会員認証はGET方式とPOST方式の2つのタイプで提供します。 * 連動のため、Contipleが提供する開発明細書に従ってAPIを開発し、会員認証メニューに登録してください。 #### **(1) POST 方式** * 連動させるサービスがPC、MOBILEプラットフォームでWEB基盤で提供される場合に適しています。 * サービスのログイン画面がWEB URL形式で提供されている場合に使用できます。 * 開発明細でCLIENT-SIDE、SERVICER-SIDEの細部2タイプを提供します。 #### **(2) GET 方式** * WEBベースのログイン画面がないサービスに適しています。 * WEBベースではないNative APPサービスの場合に適した連動方式です。 *** ### **1-2. プロセス（POST方式）** {% stepper %} {% step %} ユーザーがヘルプセンターの「お問合わせ」または「お問合わせ履歴」ページにアクセスします。 {% endstep %} {% step %} 会員認証設定が「有効」の場合、[**ログインステータスURL**](#login-status)が呼び出されます。 * [ログインステータスURL](#login-status)はガイドに従ってお客様側で実装していただく必要があり、Contipleへログインステータスを返却してください。 {% endstep %} {% step %} ユーザーがログアウト状態の場合、`status = false` を返却します。 {% endstep %} {% step %} この場合、ユーザーにログインを促すため、[**ログインURLページ**](#login)へリダイレクトされます。 * リダイレクト時に `returnUrl` パラメータが自動的に付与され、ログイン成功後に①でユーザーがアクセスしていたページへ遷移するために使用されます。 {% endstep %} {% step %} ユーザーはID、パスワードを入力してログインを行います。 {% endstep %} {% step %} ログイン成功時、④で指定された `returnUrl` へリダイレクトされます。 * プロセス上、再度②のステップに戻り、ログインステータスURLが呼び出されます。 {% endstep %} {% step %} ログイン状態の場合、`status = true` を返却し、お客様側サーバーから[**リモートログインAPI**](#remote-server)を呼び出して、顧客情報（氏名、メールアドレス、電話番号など）をContipleへ送信します。 * 送信された情報は、1:1お問い合わせの受付時に顧客情報関連フィールドへ自動入力されます。 {% endstep %} {% step %} Contipleは提供された顧客情報をもとにAccess Tokenを発行します。 {% endstep %} {% step %} お客様側サーバーは、ユーザーをお問合わせ／お問合わせ履歴ページへ遷移させ、発行されたAccess Tokenをパラメータとして付与します。 {% endstep %} {% step %} 提供されたAccess Tokenの有効性を確認後、ユーザー向けにページがレンダリングされます。 {% endstep %} {% endstepper %} *** ### **1-3.** 会員認証の設定方法 #### **①** 会員認証の有効 * \[サービス管理] → \[ヘルプセンター] → \[会員認証] に移動します。 * 会員認証を使用するには、**有効**に設定します。 #### **②** 非会員のお問い合わせ * 有効 :（お客様が）ログインしていない状態でも問い合わせの受付が可能になります。 * 無効 : ログイン状態でのみお問い合わせの受付ができるように制御されます。 #### **③** ログインタイプ * POST形式を選択します。 #### **④** URL設定 * [**ログインURL**](#login): ログインステータスURLの呼び出し後、ユーザーがログイン状態でない場合に遷移させるログイン画面のURL * [**ログインステータスURL**](#login-status): ヘルプセンターへのアクセス時、またはページ遷移時に、ユーザーのログイン状態を確認するためのURLです。 * 上記2つのURLは、下記の開発仕様書をご参照のうえ、お客様側で運用されているサービスにて実装・提供していただく必要があります。 #### **⑤** パラメータ設定 * 必要に応じて、[**リモートログインAPI**](#remote-server)を通じて Contiple に連携する顧客情報を追加することが可能です。 * 追加する情報は、リクエストヘッダーまたはクエリパラメータとして送信してください。 * なお、パラメータ名は、リモートログインAPIにてお客様側から送信するパラメータ名と同一である必要があります。 #### ⑥ 顧客情報の暗号化 * [**リモートログインAPI**](#remote-server)を通じて顧客情報を Contiple に連携する際、氏名・メールアドレス・電話番号などのデータを暗号化したい場合に有効化します。 * 本設定を有効にすると API Key が発行され、[**リモートログインAPI**](#remote-server)を呼び出す際には、ガイドに従って当該 API Key を用いて暗号化した上で送信する必要があります。 * Contiple では、受信した暗号化データを該当の API Key により復号し、データを処理します。 *** ## **➋** 開発明細書 ### **2-1.** 認証トークン作成 {% hint style="info" %} **Contiple組織Key** \[全体管理]→\[契約サービス管理]→「組織情報」から確認できます。 {% endhint %} > Token生成サンプルは以下の通りです。 パラメータ順序は必ず下記と一致している必要があります。 > > (※ Sample project > application.properties > oc.apikey= 項目に組織キーを保存) ```java private String getSHA256Token(String serviceId, String usercode, String username, String email, String phone, String returnUrl, Long time, String apiKey) throws Exception { StringBuilder sb = new StringBuilder(); // Order by follow number: sb.append(serviceId); // 1 sb.append("&"); sb.append(usercode); // 2 sb.append("&"); if (StringUtils.isNotBlank(username)) { sb.append(username); // 3 sb.append("&"); } if (StringUtils.isNotBlank(email)) { sb.append(email); // 4 sb.append("&"); } if (StringUtils.isNotBlank(phone)) { sb.append(phone); // 5 sb.append("&"); } 　if (StringUtils.isNotBlank(memberno)) { sb.append(memberno); // 6 sb.append("&"); 　} if (StringUtils.isNotBlank(returnUrl)) { sb.append(returnUrl); // 7 sb.append("&"); } sb.append(time); // 8 SecretKeySpec signingKey = new SecretKeySpec(apiKey.getBytes("UTF-8"), "HmacSHA256"); Mac mac = Mac.getInstance(signingKey.getAlgorithm()); mac.init(signingKey); byte[] rawHmac = mac.doFinal(sb.toString().getBytes("UTF-8")); return new String(Base64.encodeBase64(rawHmac)); } // Sample // Use this same input, the output is : Ah9M58CQ9RFTShjFuqziQr+0MjmJxN6+bzWxMD71moo= public static void main(String[] args) throws Exception { String s = getSHA256Token("hangame", "testusercode", "testUsername", "test@email.com", "123456789", null, 1660095873001L, "7cf2828608274a49a3f06152b2188927"); System.out.println(s); // Output: Ah9M58CQ9RFTShjFuqziQr+0MjmJxN6+bzWxMD71moo= } ``` *** ### **2-2.** POSTリモートログインAPI (From Client Side) #### **(1) インターフェース説明** * URL: https\://{domain}.oc.nhncloud.com/v2/enduser/remote.json | インターフェース名 | プロトコル | 呼び出し方向 | エンコード | 結果形式 | インターフェース説明 | | ---------------------------------- | ----- | ------ | ----- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | POSTリモートログインAPI (From Client Side) | HTTPS | POST | UTF-8 | Redirect |

ユーザー側システムで動的にフォームを生成し、ブラウザに返却します。
生成されたフォームは、自動的に API にフォーム情報を送信します。API では送信されたフォーム情報をもとに認証を行い、認証が成功した場合はログイン用の Cookie を設定します。

| {% hint style="info" %} **ユーザーシステムでの呼び出し方法**は、下段のSample project内の以下のクラスをご参照ください。 * FormLoginController.java * Method: submitLogin {% endhint %} *** #### **(2) リクエストパラメータ定義** | 名称 | 変数 | データタイプ | 必須 | 説明 | | -------------- | --------- | ------------ | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | サービスID | service | Varchar(50) | O | サービスID | | ユーザーID | usercode | Varchar(50) | O | ユーザーID，唯一のユーザーであることを表示 | | ユーザー名 | username | Varchar(50) | X | ユーザー名 | | ユーザーメールアドレス | email | Varchar(100) | X | ユーザーメールアドレス | | 電話番号 | phone | Varchar(20) | X | 電話番号 | | 会員番号 | memberno | Varchar(50) | X | 会員番号 | | 現在時間のtimestamp | time | Long | O | 呼び出し時間が3分を超過した場合、タイムアウトアラートが表示されます。 | | 認証Token | token | Varchar | O |

以下のパラメータ値と組織Keyにより算出されたSHA256

| | リターン画面URL | returnUrl | Varchar | X | 設定およびログインに成功した場合、URLアドレスに移動 | *** #### **(3) 結果データ** * returnUrl パラメータが存在する場合、指定された returnUrl へ遷移します。 * returnUrl パラメータが存在しない場合は、文字列（SUCCESS）を返却します。 *** ### **2-3.** POSTリモートログインAPI (From Server Side) #### **(1) インターフェース説明** * URL: https\://{domain}.oc.nhncloud.com/api/v2/enduser/remote.json | インターフェース名 | プロトコル | 呼び出し方向 | エンコード | 結果形式 | インターフェース説明 | | ---------------------------------- | ----- | ------ | ----- | ------ | -------------------------------------------------------------- | | POSTリモートログインAPI (From Server Side) | HTTPS | POST | UTF-8 | String | ユーザーはサーバーから直接APIを呼び出します。APIによるログイン認証が成功した場合、ログインCookieが設定されます。 | {% hint style="info" %} **ユーザーシステムでの呼び出し方法**は、下段のSample project内の以下のクラスをご参照ください。 * ApiLoginController.java * Method: submitLogin {% endhint %} *** #### **(2) リクエストパラメータ定義** | 名称 | 変数 | データタイプ | 必須 | 説明 | | -------------- | -------- | ------------ | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | サービスID | service | Varchar(50) | O | サービスID | | ユーザーID | usercode | Varchar(50) | O | ユーザーID，唯一のユーザーであることを表示 | | ユーザー名 | username | Varchar(50) | X | ユーザー名 | | ユーザーメールアドレス | email | Varchar(100) | X | ユーザーメールアドレス | | 電話番号 | phone | Varchar(20) | X | 電話番号 | | 会員番号 | memberno | Varchar(50) | X | 会員番号 | | 現在時間のtimestamp | time | Long | O | 呼び出し時間が3分を超過した場合、タイムアウトアラートが表示されます。 | | 認証Token | token | Varchar | O |

以下のパラメータ値と組織Keyにより算出されたSHA256

| *** #### **(3) Response Data** > 返却された content の値を、ヘルプセンター呼び出し時に\ > URLパラメータである accessToken に指定し、Contiple に連携します。 > > * 例 : ```json { "header": { "resultCode": 200, "resultMessage": "", "isSuccessful": true }, "result": { "content": "xxxxxxaccessTokenxxxxxxx" } } ``` *** ### **2-4.** POSTログインURL (ユーザー) #### **(1) インターフェース説明** * URL: サービス側から提供 | インターフェース名 | プロトコル | 呼び出し方向 | エンコード | 結果形式 | | ------------------ | ----- | ------ | ----- | -------- | | POSTログインURL (ユーザー) | HTTPS | GET | UTF-8 | Redirect | > サービス側のログインURLには以下の機能が必要です。 > > * **未ログイン状態** > * ログイン画面を表示 > * アカウント／パスワードによるログインを実行 > * ログイン成功後、Cookie を生成し、ログイン状態を記録\ > （ログイン状態チェック時に使用） > * ログイン成功後、Client または Server 側から顧客情報を Contiple に連携\ > （[POST リモートログインAPI（From Client Side）](#remote-client)、[POST リモートログインAPI（From Server Side）](#remote-server)を参照） > * **ログイン状態** > * ログイン成功後、Client または Server 側から顧客情報を Contiple に連携\ > （[POST リモートログインAPI（From Client Side）](#remote-client)、[POST リモートログインAPI（From Server Side）](#remote-server)を参照） #### **(2) リクエストパラメータ定義** | 名称 | 変数 | データタイプ | 必須 | 説明 | | ------- | --------- | ------- | -- | --------------- | | リターンURL | returnUrl | Varchar | O | ログイン成功後に移動するURL | > **SSOログイン機能の説明** > > * **未ログイン状態** > * ① ログイン画面に移動 > * ② ユーザーログイン > * ③ サービス側サーバーにてユーザーのログイン処理を実施し、ログインユーザーに関する Cookie を生成 > * ④ POST リモートログインAPI を呼び出し\ > （[POST リモートログインAPI（From Client Side）](#remote-client)、[POST リモートログインAPI（From Server Side）](#remote-server)を参照） > * **ログイン状態** > * ① POST リモートログインAPI を呼び出し\ > （[POST リモートログインAPI（From Client Side）](#remote-client)、[POST リモートログインAPI（From Server Side）](#remote-server)を参照） > **POSTリモートログインAPIの呼び出し方法** > > 1. **POSTリモートログイン(From client side)** > * ① ユーザー情報とAPI Key基準でログインtoken作成 > > * ② ユーザー情報とtokenをブラウザーにリダイレクト > > * ③ 画面でForm作成, 詳しいパラメーターは[POST リモートログインAPI（From Client Side）](#remote-client)参考 > > * ④ Form提出 > > * ⑤ POSTリモートログインAPIによりユーザー情報とtoken送信 > > * ⑥ ログインに成功した後、{returnUrl}に移動 > 2. **POSTリモートログイン(From server side)** > * ① ユーザー情報とAPI Key基準でログインtoken作成 > * ② サーバーからPOSTリモートログインAPI(From server side)呼び出し > * ③ API呼び出しパラメータ(usercodeとtime)をreturnUrlの後に追加 > * 例) > * ④ {returnUrl}に移動 *** ### **2-5.** POSTログインステータスURL(ユーザー) #### **(1) インターフェース説明** * URL: サービス側から提供 | インターフェース名 | プロトコル | 呼び出し方向 | エンコード | インターフェース説明 | 結果形式 | | ---------------------- | ----- | ------ | ----- | ---------------------------------------------------------------------------------------------------- | ---- | | POSTログインステータスURL(ユーザー) | HTTPS | GET | UTF-8 |

ユーザーは Cookie 情報を基にログイン状態を判定し、JSON 形式のデータを返却します。
なお、サービス側サーバーでは、レスポンスに対してクロスドメイン接続の設定が必要です。

| JSON | > **Cross domain接続設定**方法は下記を参照してください。 > > ``` > response.addHeader("Access-Control-Allow-Origin", request.getHeader("origin")); > response.addHeader("Access-Control-Allow-Credentials", "true"); > ``` {% hint style="info" %} **ユーザーシステムでの呼び出し方法**は、下段のSample project内の以下のクラスをご参照ください。 * FormLoginController.java * Method: loginStatus {% endhint %} *** #### **(2) リクエストパラメータ定義** * 無し *** #### **(3) 結果データ** | 名称 | 変数 | データタイプ | 必須 | 説明 | | ------------------- | -------- | ----------- | -- | --------------------------------------------------------------- | | javascript function | login | Boolean | O |

ログイン状態

| | ユーザーID | usercode | Varchar(50) | X | ユーザーID(ユニーク値). ログイン状態 = trueの場合、必須 | *** #### **(4) Response Body** ```json { "login": "true", "usercode":"usercodeXXX" } { "login": "false", "usercode": null } ``` *** ## **➌** 適用例 ### **3-1. Sample Code** * Sample Code ダウンロード {% file src="/files/gWqFhWiw9632kBvXmc1m" %} *** ### **3-2.** iframeを利用したヘルプセンターの例 **(1) iframeを利用してContipleヘルプセンターをユーザーページに挿入** * Sample Codeファイルのうち「oc\_sso\_sample/src/main/resources/templates/help\_frame.ftl」を参照してください。 * iframeの名前は必ずid="ocPage"と指定しなければなりません。 ``` ``` * ページにviewportを設定する際、mobile／webブラウザのどちらでもヘルプセンターを使用できます。 ``` ``` *** **(2) Parentページ内でContipleヘルプセンターの高さを確認し、iframeのheightを調整** * help\_frame.ftl ファイルのうち、javascript コードを参照してください。 ```javascript // Listener for OC content height change window.addEventListener('message',function(event){ // Set iframe height if(event.data > 0) { updateHeight(event.data); } }); var updateHeight = function(wrapHeight) { var iframe = window.document.getElementById('ocPage'); if(iframe != null) { iframe.style.height = '0px'; var setHeight = (document.body.clientHeight > document.body.scrollHeight) ? document.body.clientHeight : document.body.scrollHeight; var margin = 70; setHeight = setHeight > wrapHeight ? setHeight : wrapHeight; iframe.style.height = setHeight + margin + "px"; } }; ``` *** **(3) ログイン処理後に設定するクッキーは、ユーザーページから取得可能** * help\_frame.ftl ファイルのうち、javascript コードを参照してください。 ```javascript // get cookie function getCookie(name) { var arr,reg=new RegExp("(^| )"+name+"=([^;]*)(;|$)"); if(arr=document.cookie.match(reg)) return unescape(arr[2]); else return null; } $.when( $.ready ).then(function() { var ssotoken = getCookie("sso_test_login"); var usercode = getCookie("usercode"); if(ssotoken != null && usercode != null) { var signout = $("#signout"); $("#signout").html("Welcome " + usercode + "! Sign out"); $("#signout").show(); $("#signin").hide(); } }); ```