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 online 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。
