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 打開登入連結。

介面說明
請求方式:GET
| 參數 | 必填 | 說明 |
| appId | 是 | 主帳號 ID。與子帳號 SSO 介面使用同一個 appId。 |
| 條件必填 | 聯絡人郵箱。與 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。