SSO 聯絡人介面

本文說明如何用聯絡人的郵箱或第三方使用者 ID 完成單一登入。它與子帳號 SSO 介面使用同一套 appId 和 Secret Key,但介面網址、簽章欄位和登入後的去向不同。子帳號的建立與角色請仍使用子帳號 SSO 介面。


概述

傳入聯絡人郵箱或第三方使用者 ID 後,系統校驗簽章並登入該聯絡人。登入成功後:

- 傳了有效的 surveyId 時,直接進入該問卷作答頁,優先順序高於 returnUrl。

- 未傳 surveyId,或 surveyId 無效時,依 returnUrl 跳轉。子帳號和一般聯絡人都生效,也可以跳到聯絡人頁。

- 未傳 returnUrl 時,子帳號進入問卷列表,一般聯絡人進入聯絡人主頁。


使用場景

- 業務系統已有聯絡人郵箱或第三方使用者 ID,希望使用者免密進入 SurveyMars。

- 登入後直接打開某份問卷作答,可傳 surveyId。

- 子帳號和一般聯絡人都可以依 returnUrl 跳轉,包括聯絡人頁。


接入前準備

1. 使用主帳號登入 SurveyMars,在 「我的帳戶」 查看 appId(帳戶 ID)。

2. 聯絡客服開通 Secret Key。金鑰只在伺服器端參與簽章,不要寫入 URL,也不要放到前端程式碼中。

3. 在伺服器端按本文規則產生 SHA256 簽章,再用 GET 打開登入連結。


我的帳戶中的 appId



介面說明

請求方式:GET

介面連結:https://surveymars.com/app/login/contact/verify?appId=&email=&thirdUserId=&ts=&language=&returnUrl=&surveyId=&sign=


參數 必填 說明
appId 是 主帳號 ID。與子帳號 SSO 介面使用同一個 appId。
email 條件必填 聯絡人郵箱。與 thirdUserId 至少提供一個。主帳號未開啟「聯絡人郵箱可為空」時,email 必填。
thirdUserId 條件必填 第三方使用者 ID。與 email 至少提供一個。兩者都傳時,驗證忽略 thirdUserId,但該值仍參與簽章。
language 否 提示資訊的語言和问卷语言。不參與簽章。
returnUrl 否 登入成功後的跳轉頁。子帳號和一般聯絡人都生效,可以跳到聯絡人頁。不參與簽章。網址中含 & 或 ? 時,必須把整個 returnUrl 做一次 URL 編碼。
surveyId 否 問卷 ID,不參與簽章。有效時直接進入該問卷作答頁,優先順序高於 returnUrl。無效時跳轉到 returnUrl。
ts 是 時間戳記,從 1970-01-01 00:00:00(UTC)起至目前的秒數。有效期為 60 秒。URL 中的 ts 必須與簽章使用的 ts 相同,請在打開連結前即時產生。
sign 是 加密簽章。sign 為對拼接後的明文字串做 SHA256 得到的十六進位小寫字串。明文為 appId + email + thirdUserId + ts + Secret Key。拼接順序須嚴格一致。Secret Key 只參與伺服器端拼接,不出現在瀏覽器網址列。詳見下文「簽章計算」。


簽章計算

簽章計算規則


1. 將參與簽章的欄位按固定順序直接首尾拼接為一條字串(中間無分隔符)。順序為:appId + email + thirdUserId + ts + Secret Key。未傳的 email 或 thirdUserId 按空字串參與拼接,不能省掉這一段,也不能用占位符代替。Secret Key 只參與伺服器端拼接,不出現在瀏覽器網址列。


2. 對該字串做 SHA256,取十六進位小寫字串作為參數 sign 的值。


3. 查詢參數中的 language、returnUrl、surveyId 不參與上述簽章字串拼接;僅按第 1 步所列欄位順序計算。


4. ts 為從 1970-01-01 00:00:00(UTC)起至目前的秒數,有效期為 60 秒。請在使用者即將跳轉前即時產生 ts 與 sign,且 URL 中的 ts 必須與簽章使用的 ts 相同。URL 編碼不能改變用於拼接的原始值。


5. 如需線上計算 SHA256 以核對拼接是否正確,可將得到的明文字串貼到第三方工具(例如 LZL 線上 SHA256 雜湊)中產生。正式環境仍建議在伺服器端程式碼中產生 sign,勿將 Secret Key 暴露給瀏覽器。


6. 不要把子帳號 SSO 的簽章串用到本介面。子帳號介面的欄位是 appId、email、userName、roleId 和 ts,本介面沒有 userName 和 roleId。



郵箱與 thirdUserId

1. email 和 thirdUserId 至少填寫一個。

2. 兩個都填寫時,驗證只使用 email,忽略 thirdUserId。thirdUserId 仍須按原值參與簽章,並可以保留在 URL 中。

3. 主帳號未開啟「聯絡人郵箱可為空」時,必須傳 email。


登入後的跳轉

1. 傳了有效的 surveyId:登入成功後直接進入該問卷作答頁。優先順序高於 returnUrl。

2. 未傳 surveyId,或 surveyId 為無效參數:依 returnUrl 跳轉。不再限制只有子帳號才跳轉,一般聯絡人也可以跳轉,包括聯絡人頁。

3. 未傳 returnUrl:子帳號進入問卷列表,一般聯絡人進入聯絡人主頁。


returnUrl 編碼

returnUrl 裡如果有 & 或 ?,必須把整個 returnUrl 做一次 URL 編碼,再放入登入連結。不要只編碼其中一段,也不要編碼兩次。未整體編碼時,& 和 ? 會被當成登入連結自己的分隔符,伺服器端識別不到完整網址。

例如,原始網址是 https://surveymars.com/app/contacts?tab=1&id=2,編碼一次後寫入:

returnUrl=https%3A%2F%2Fsurveymars.com%2Fapp%2Fcontacts%3Ftab%3D1%26id%3D2

returnUrl 不參與簽章,編碼不會改變 sign。



重要說明

- Secret Key 只在伺服器端使用,不要出現在瀏覽器網址列。

- 本介面用於聯絡人登入,不用於建立子帳號或設定子帳號角色。

- email 中的 @ 等字元放入 URL 時請做編碼;參與簽章的仍是編碼前的原始值。

- surveyId 非必填,不參與簽章。有效時進入作答頁;無效時跳轉到 returnUrl。

- returnUrl 含 & 或 ? 時,整個網址只做一次 URL 編碼。


常見問題

問:這個介面和子帳號 SSO 介面有什麼區別?
答:子帳號介面網址是 /app/login/sso/verify,用於建立或登入子帳號。聯絡人介面網址是 /app/login/contact/verify,用郵箱或第三方使用者 ID 登入聯絡人。兩者的簽章欄位不同,不能混用 sign。


問:只傳 thirdUserId、不傳 email 可以嗎?
答:可以,但主帳號必須已開啟「聯絡人郵箱可為空」。未開啟時,email 仍是必填。簽章裡未傳的那個欄位按空字串拼接。


問:email 和 thirdUserId 都傳了,為什麼還是按郵箱登入?
答:兩個都傳時,驗證忽略 thirdUserId,只按 email 識別聯絡人。thirdUserId 仍然要參與簽章。


問:一般聯絡人可以依 returnUrl 跳轉嗎?
答:可以。returnUrl 不再只對子帳號生效,一般聯絡人也可以跳轉,包括聯絡人頁。傳了有效 surveyId 時,優先進入該問卷作答頁。


問:surveyId 和 returnUrl 都傳了,會打開哪一頁?
答:有效的 surveyId 優先進入該問卷作答頁,優先順序高於 returnUrl。surveyId 無效或未傳時,才依 returnUrl 跳轉。


問:returnUrl 裡有 & 或 ?,為什麼跳轉網址不完整?
答:請把整個 returnUrl 做一次 URL 編碼。例如 ? 編成 %3F,& 編成 %26。不要只編碼半段,也不要編碼兩次。


問:為什麼提示驗簽失敗?
答:請核對 Secret Key 是否正確,拼接順序須為 appId、email、thirdUserId、ts、Secret Key。未傳的 email 或 thirdUserId 按空字串拼接。同時確認 ts 仍在 60 秒有效期內,且 URL 編碼未改變用於拼接的原始值。language、returnUrl 和 surveyId 不要加入簽章串。


問:ts 為何很快就過期?
答:正式環境要求時間戳記與伺服器時間相差在 60 秒內,請在使用者即將跳轉前即時產生 ts 與 sign。

這篇文章有多大幫助?