Interfaz SSO de contactos
Este artículo explica cómo iniciar sesión de un contacto con una dirección de correo electrónico o un ID de usuario de un tercero. Usa el mismo appId y Secret Key que la interfaz SSO de subcuentas, pero la URL, los campos de la firma y la página de destino son diferentes. Crea subcuentas y asigna roles con la interfaz SSO de subcuentas.
Descripción general
Envía el correo electrónico del contacto o el ID de usuario de un tercero. SurveyMars comprueba la firma e inicia sesión en ese contacto.
- Si el contacto es una subcuenta, SurveyMars abre returnUrl. Si se omite returnUrl, abre la lista de encuestas.
- Si el contacto no es una subcuenta, SurveyMars ignora returnUrl y abre la página de inicio del contacto.
Casos de uso
- Tu sistema ya tiene un correo electrónico de contacto o un ID de usuario de un tercero, y quieres acceso a SurveyMars sin contraseña.
- Un contacto de subcuenta llega a returnUrl. Los demás contactos omiten returnUrl y llegan a la página de inicio del contacto.
Antes de empezar
1. Inicia sesión con la cuenta principal y copia appId desde Mi cuenta.
2. Pide al soporte que habilite la Secret Key. Usa la clave solo en tu servidor. No la pongas en la URL ni en el código del front-end.
3. Genera la firma SHA256 en tu servidor y luego abre el enlace de inicio de sesión con GET.
Solicitud
Método: GET
| Parámetro | Obligatorio | Descripción |
| appId | Sí | ID de la cuenta principal. Usa el mismo appId que la interfaz SSO de subcuentas. |
| Condicional | Correo electrónico del contacto. Proporciona email o thirdUserId, o ambos. email es obligatorio cuando la cuenta principal no ha permitido un correo electrónico de contacto vacío. | |
| thirdUserId | Condicional | ID de usuario de un tercero. Proporciona email o thirdUserId, o ambos. Si se envían ambos, la verificación usa solo email. thirdUserId sigue formando parte de la firma. |
| language | No | Idioma de los mensajes de aviso. No participa en la firma. |
| returnUrl | No | Página que se abre después de que una subcuenta inicia sesión. SurveyMars la sigue para un contacto de subcuenta e la ignora en otros casos. No participa en la firma. |
| ts | Sí | Segundos transcurridos desde 1970-01-01 00:00:00 UTC. Sigue siendo válido durante 60 segundos. El ts de la URL debe coincidir con el ts usado en la firma. Generarlo cuando el usuario esté a punto de abrir el enlace. |
| sign | Sí | Firma. sign es el SHA256 hexadecimal en minúsculas del texto sin formato concatenado: appId + email + thirdUserId + ts + Secret Key. El orden debe coincidir exactamente. La Secret Key solo se concatena en el servidor y no debe aparecer en la barra de direcciones del navegador. Consulta Generar la firma a continuación. |
Generar la firma
Reglas de la firma
1. Une los campos de firma en un orden fijo y sin separadores: appId + email + thirdUserId + ts + Secret Key. Si se omite email o thirdUserId, usa una cadena vacía en esa posición. No elimines el campo ni lo reemplaces por un marcador de posición. La Secret Key solo se concatena en el servidor y no debe aparecer en la barra de direcciones del navegador.
2. Aplica SHA256 a esa cadena y usa el valor hexadecimal en minúsculas como sign.
3. language y returnUrl no participan en la firma. Usa solo los campos y el orden del paso 1.
4. ts es la cantidad de segundos desde 1970-01-01 00:00:00 UTC. Sigue siendo válido durante 60 segundos. Genera ts y sign cuando el usuario esté a punto de abrir el enlace, y usa el mismo ts en la URL. La codificación URL no debe cambiar los valores originales usados en la firma.
5. Para comprobar la cadena concatenada, pégala en una herramienta SHA256 como LZL online SHA256. En producción, genera sign en tu servidor. No expongas la Secret Key al navegador.
6. No reutilices una firma SSO de subcuenta. Esa cadena usa appId, email, userName, roleId y ts. Esta interfaz no usa userName ni roleId.
Por ejemplo：
http://surveymars.com/app/login/contact/verify?appId=TTeEB8&[email protected]&ts=1790760357&language=2&returnUrl=https://surveymars.com/app/usercenter&sign=26c0c7d9da5e38c61d4aeecb223336d7a259cad0b75c8ff912855421fd832a4e
Correo electrónico e ID de usuario de terceros
1. Envía al menos uno de los campos email y thirdUserId.
2. Si envías ambos, la verificación usa email e ignora thirdUserId. Mantén el thirdUserId original en la firma y puedes conservarlo en la URL.
3. Si la cuenta principal no ha permitido un correo electrónico de contacto vacío, email es obligatorio.
4. Si esta configuración está desactivada, contacta con soporte para activar "Allow empty contact email." Una vez activada, puedes añadir un contacto sin correo electrónico.
Dónde termina el contacto
1. Contacto de subcuenta: SurveyMars abre returnUrl. Si se omite returnUrl, abre la lista de encuestas.
2. Otros contactos: SurveyMars ignora returnUrl y abre la página de inicio del contacto.
Notas importantes
- Mantén la Secret Key en tu servidor. No la coloques en la barra de direcciones del navegador.
- Esta interfaz inicia sesión en un contacto. No crea una subcuenta ni asigna un rol de subcuenta.
- Codifica en URL caracteres como @ en el correo electrónico. Firma el valor original, no el valor codificado.
Preguntas frecuentes
¿En qué se diferencia de SSO de subcuenta?
SSO de subcuenta usa /app/login/sso/verify para crear o iniciar sesión en una subcuenta. El inicio de sesión de contacto usa /app/login/contact/verify con un correo electrónico o un ID de usuario de un tercero. Los campos de la firma son diferentes. No reutilices sign.
¿Puedo enviar solo thirdUserId?
Sí, si la cuenta principal permite un correo electrónico de contacto vacío. De lo contrario, email es obligatorio. Usa una cadena vacía para el campo omitido en la firma.
Envié email y thirdUserId. ¿Por qué el inicio de sesión usa el email?
Cuando ambos están presentes, la verificación ignora thirdUserId y coincide con el contacto por email. thirdUserId sigue formando parte de la firma.
¿Por qué un contacto que no es una subcuenta omitió returnUrl?
returnUrl solo se aplica cuando el contacto es una subcuenta. De lo contrario, SurveyMars lo ignora y abre la página de inicio del contacto.
¿Por qué falla la verificación de la firma?
Comprueba la Secret Key. Une appId, email, thirdUserId, ts y la Secret Key en ese orden. Usa una cadena vacía para un email o thirdUserId omitido. Confirma que ts siga dentro de 60 segundos y que la codificación URL no haya cambiado los valores originales. No incluyas language ni returnUrl.
¿Por qué ts expira tan rápido?
En producción, ts debe estar dentro de 60 segundos de la hora del servidor. Genera ts y sign cuando el usuario esté a punto de abrir el enlace.
