SSO 聯絡人介面
本文說明如何使用電子郵件地址或第三方使用者 ID 將聯絡人登入。它使用與子帳號 SSO 介面相同的 appId 和 Secret Key，但 URL、簽章欄位與登入頁面不同。請使用子帳號 SSO 介面建立子帳號並設定角色。
概覽
傳送聯絡人電子郵件或第三方使用者 ID。SurveyMars 會檢查簽章並將該聯絡人登入。
- 如果聯絡人是子帳號，SurveyMars 會開啟 returnUrl。若省略 returnUrl，則會開啟問卷列表。
- 如果聯絡人不是子帳號，SurveyMars 會忽略 returnUrl，並開啟聯絡人首頁。
使用情境
- 您的系統已經有聯絡人電子郵件或第三方使用者 ID，並且希望以免密碼方式存取 SurveyMars。
- 子帳號聯絡人會進入 returnUrl。其他聯絡人會略過 returnUrl，並進入聯絡人首頁。
開始之前
1. 使用主帳號登入，並從 我的帳戶 複製 appId。
2. 請聯絡支援啟用 Secret Key。請僅在您的伺服器上使用該金鑰，不要將它放在 URL 或前端程式碼中。
3. 在您的伺服器上建立 SHA256 簽章，然後使用 GET 開啟登入連結。
請求
方法：GET
| 參數 | 必填 | 說明 |
| appId | Yes | 主帳號 ID。請使用與子帳號 SSO 介面相同的 appId。 |
| Conditional | 聯絡人電子郵件。可提供 email 或 thirdUserId，或兩者都提供。當主帳號未允許空白聯絡人電子郵件時，email 為必填。 | |
| thirdUserId | Conditional | 第三方使用者 ID。可提供 email 或 thirdUserId，或兩者都提供。若兩者都送出，驗證只會使用 email。thirdUserId 仍會納入簽章。 |
| language | No | 提示訊息的語言。此欄位不會納入簽章。 |
| returnUrl | No | 子帳號登入後要開啟的頁面。SurveyMars 會在聯絡人為子帳號時依此跳轉，否則會忽略。此欄位不會納入簽章。 |
| ts | Yes | 自 1970-01-01 00:00:00 UTC 起的秒數。有效期為 60 秒。URL 中的 ts 必須與簽章中使用的 ts 相同。請在使用者即將開啟連結時產生。 |
| sign | Yes | 簽章。sign 是串接明文 appId + email + thirdUserId + ts + Secret Key 後，使用小寫十六進位表示的 SHA256。順序必須完全一致。Secret Key 只會在伺服器端串接，且不得出現在瀏覽器位址列中。請參閱下方的建立簽章。 |
建立簽章
簽章規則
1. 依固定順序串接簽章欄位，且不加任何分隔符號：appId + email + thirdUserId + ts + Secret Key。如果省略 email 或 thirdUserId，則在該位置使用空字串。不要刪除欄位，也不要以佔位符取代。Secret Key 只會在伺服器端串接，且不得出現在瀏覽器位址列中。
2. 使用 SHA256 對該字串雜湊，並將小寫十六進位值作為 sign。
3. language 與 returnUrl 不會納入簽章。只使用步驟 1 中的欄位與順序。
4. ts 是自 1970-01-01 00:00:00 UTC 起的秒數。它的有效期為 60 秒。請在使用者即將開啟連結時產生 ts 與 sign，並在 URL 中使用相同的 ts。URL 編碼不得更改簽章中使用的原始值。
5. 若要檢查串接後的字串，請將其貼到 SHA256 工具，例如 LZL 線上 SHA256。正式環境中，請在您的伺服器上產生 sign。不要向瀏覽器暴露 Secret Key。
6. 不要重複使用子帳號 SSO 簽章。該字串使用 appId、email、userName、roleId 與 ts。本介面不使用 userName 或 roleId。
例如：
http://surveymars.com/app/login/contact/verify?appId=TTeEB8&[email protected]&ts=1790760357&language=2&returnUrl=https://surveymars.com/app/usercenter&sign=26c0c7d9da5e38c61d4aeecb223336d7a259cad0b75c8ff912855421fd832a4e
電子郵件與第三方使用者 ID
1. 至少傳送 email 與 thirdUserId 其中之一。
2. 如果兩者都傳，驗證會使用 email 並忽略 thirdUserId。請在簽章中保留原始 thirdUserId，且可保留在 URL 中。
3. 如果主帳號尚未允許空白聯絡人電子郵件，則 email 為必填。
4. 如果此設定已關閉，請聯絡支援開啟「允許空白聯絡人電子郵件」。開啟後，您可以新增沒有電子郵件的聯絡人。
聯絡人的登入位置
1. 子帳號聯絡人：SurveyMars 會開啟 returnUrl。若省略 returnUrl，則會開啟問卷列表。
2. 其他聯絡人：SurveyMars 會忽略 returnUrl，並開啟聯絡人首頁。
重要說明
- 請將 Secret Key 保留在您的伺服器上，不要放在瀏覽器位址列中。
- 此介面會登入聯絡人，不會建立子帳號或設定子帳號角色。
- 請對 email 中的 @ 等字元進行 URL 編碼。簽章應使用原始值，而非編碼後的值。
常見問題
這與子帳號 SSO 有何不同？
子帳號 SSO 使用 /app/login/sso/verify 建立或登入子帳號。聯絡人登入則使用 /app/login/contact/verify，並搭配電子郵件或第三方使用者 ID。簽章欄位不同，請勿重複使用 sign。
我可以只傳 thirdUserId 嗎？
可以，前提是主帳號允許空白聯絡人電子郵件。否則 email 為必填。簽章中未提供的欄位請使用空字串。
我同時傳了 email 和 thirdUserId，為什麼登入會使用 email？
當兩者都存在時，驗證會忽略 thirdUserId，並以 email 比對聯絡人。thirdUserId 仍會納入簽章。
為什麼不是子帳號的聯絡人會略過 returnUrl？
returnUrl 只會在聯絡人是子帳號時套用。否則 SurveyMars 會忽略它並開啟聯絡人首頁。
為什麼簽章驗證會失敗？
請檢查 Secret Key。依 appId、email、thirdUserId、ts 與 Secret Key 的順序串接。若省略 email 或 thirdUserId，請使用空字串。確認 ts 仍在 60 秒內，且 URL 編碼未更改原始值。不要包含 language 或 returnUrl。
為什麼 ts 很快就過期？
在正式環境中，ts 必須與伺服器時間相差 60 秒以內。請在使用者即將開啟連結時產生 ts 與 sign。
