Интерфейс SSO для контактов
В этой статье объясняется, как выполнить вход для контакта с помощью адреса электронной почты или ID стороннего пользователя. Он использует тот же appId и Secret Key, что и SSO-интерфейс для субаккаунтов, но 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 основного аккаунта. Используйте тот же appId, что и в SSO-интерфейсе для субаккаунтов. |
| 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 секунд. ts в URL должен совпадать с ts, использованным в подписи. Генерируйте его в момент, когда пользователь собирается открыть ссылку. |
| sign | Yes | Подпись. 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 не участвуют в подписи. Используйте только поля и порядок из шага 1.
4. ts — это количество секунд с 1970-01-01 00:00:00 UTC. Он действителен в течение 60 seconds. Генерируйте ts и sign в момент, когда пользователь собирается открыть ссылку, и используйте тот же ts в URL. 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
Email и ID стороннего пользователя
1. Отправьте как минимум одно из полей: email и thirdUserId.
2. Если вы отправляете оба, проверка использует email и игнорирует thirdUserId. Сохраняйте исходный thirdUserId в подписи, и его можно оставить в URL.
3. Если в основном аккаунте не разрешен пустой адрес электронной почты контакта, email обязателен.
4. Если эта настройка выключена, обратитесь в поддержку, чтобы включить "Allow empty contact email." После включения можно добавить контакт без email.
Куда попадает контакт
1. Контакт субаккаунта: SurveyMars открывает returnUrl. Если returnUrl не указан, открывается список опросов.
2. Другие контакты: SurveyMars игнорирует returnUrl и открывает домашнюю страницу контакта.
Важные примечания
- Храните Secret Key на своем сервере. Не размещайте его в адресной строке браузера.
- Этот интерфейс выполняет вход контакта. Он не создает субаккаунт и не назначает роль субаккаунта.
- Кодируйте в URL такие символы, как @, в email. Подписывайте исходное значение, а не закодированное.
Часто задаваемые вопросы
Чем это отличается от SSO для субаккаунтов?
SSO для субаккаунтов использует /app/login/sso/verify для создания или входа в субаккаунт. Вход для контакта использует /app/login/contact/verify с email или 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 в момент, когда пользователь собирается открыть ссылку.
