Interface SSO Contacts
Cet article explique comment connecter un contact avec une adresse e-mail ou un identifiant utilisateur tiers. Il utilise le même appId et la même Secret Key que l’interface SSO des sous-comptes, mais l’URL, les champs de signature et la page de destination sont différents. Créez des sous-comptes et définissez des rôles avec l’interface SSO des sous-comptes.
Aperçu
Envoyez l’e-mail du contact ou son identifiant utilisateur tiers. SurveyMars vérifie la signature et connecte ce contact.
- Si le contact est un sous-compte, SurveyMars ouvre returnUrl. Si returnUrl est omis, la liste des enquêtes s’ouvre.
- Si le contact n’est pas un sous-compte, SurveyMars ignore returnUrl et ouvre la page d’accueil du contact.
Cas d’utilisation
- Votre système dispose déjà d’une adresse e-mail de contact ou d’un identifiant utilisateur tiers, et vous souhaitez un accès sans mot de passe à SurveyMars.
- Un contact de sous-compte arrive sur returnUrl. Les autres contacts ignorent returnUrl et arrivent sur la page d’accueil du contact.
Avant de commencer
1. Connectez-vous avec le compte principal et copiez appId depuis Mon compte.
2. Demandez au support d’activer la Secret Key. Utilisez la clé uniquement sur votre serveur. Ne la placez pas dans l’URL ni dans le code côté client.
3. Générez la signature SHA256 sur votre serveur, puis ouvrez le lien de connexion avec GET.
Requête
Méthode : GET
| Paramètre | Obligatoire | Description |
| appId | Oui | ID du compte principal. Utilisez le même appId que pour l’interface SSO des sous-comptes. |
| Conditionnel | E-mail du contact. Fournissez email ou thirdUserId, ou les deux. email est requis lorsque le compte principal n’autorise pas une adresse e-mail de contact vide. | |
| thirdUserId | Conditionnel | Identifiant utilisateur tiers. Fournissez email ou thirdUserId, ou les deux. Si les deux sont envoyés, la vérification utilise uniquement email. thirdUserId est tout de même inclus dans la signature. |
| language | Non | Langue des messages d’invite. Elle n’est pas incluse dans la signature. |
| returnUrl | Non | Page à ouvrir après la connexion d’un sous-compte. SurveyMars la suit pour un contact de sous-compte et l’ignore sinon. Elle n’est pas incluse dans la signature. |
| ts | Oui | Secondes depuis le 1970-01-01 00:00:00 UTC. Valide pendant 60 secondes. Le ts dans l’URL doit correspondre au ts utilisé dans la signature. Générez-le lorsque l’utilisateur est sur le point d’ouvrir le lien. |
| sign | Oui | Signature. sign est le SHA256 hexadécimal en minuscules du texte en clair concaténé : appId + email + thirdUserId + ts + Secret Key. L’ordre doit correspondre exactement. La Secret Key n’est concaténée que côté serveur et ne doit pas apparaître dans la barre d’adresse du navigateur. Voir Générer la signature ci-dessous. |
Générer la signature
Règles de signature
1. Concaténez les champs de signature dans un ordre fixe, sans séparateur : appId + email + thirdUserId + ts + Secret Key. Si email ou thirdUserId est omis, utilisez une chaîne vide à cette position. Ne supprimez pas le champ et ne le remplacez pas par un texte indicatif. La Secret Key n’est concaténée que côté serveur et ne doit pas apparaître dans la barre d’adresse du navigateur.
2. Hachez cette chaîne avec SHA256 et utilisez la valeur hexadécimale en minuscules comme sign.
3. language et returnUrl ne sont pas inclus dans la signature. Utilisez uniquement les champs et l’ordre de l’étape 1.
4. ts est le nombre de secondes écoulées depuis le 1970-01-01 00:00:00 UTC. Il reste valide pendant 60 secondes. Générez ts et sign lorsque l’utilisateur est sur le point d’ouvrir le lien, et utilisez le même ts dans l’URL. L’encodage URL ne doit pas modifier les valeurs d’origine utilisées dans la signature.
5. Pour vérifier la chaîne concaténée, collez-la dans un outil SHA256 comme LZL online SHA256. En production, générez sign sur votre serveur. N’exposez pas la Secret Key au navigateur.
6. Ne réutilisez pas une signature SSO de sous-compte. Cette chaîne utilise appId, email, userName, roleId et ts. Cette interface n’utilise pas userName ni roleId.
Par exemple：
http://surveymars.com/app/login/contact/verify?appId=TTeEB8&[email protected]&ts=1790760357&language=2&returnUrl=https://surveymars.com/app/usercenter&sign=26c0c7d9da5e38c61d4aeecb223336d7a259cad0b75c8ff912855421fd832a4e
E-mail et identifiant utilisateur tiers
1. Envoyez au moins l’un des deux : email et thirdUserId.
2. Si vous envoyez les deux, la vérification utilise email et ignore thirdUserId. Conservez la valeur d’origine de thirdUserId dans la signature, et vous pouvez la conserver dans l’URL.
3. Si le compte principal n’a pas autorisé une adresse e-mail de contact vide, email est requis.
4. Si ce réglage est désactivé, contactez le support pour activer "Allow empty contact email." Une fois activé, vous pouvez ajouter un contact sans e-mail.
Destination du contact
1. Contact de sous-compte : SurveyMars ouvre returnUrl. Si returnUrl est omis, la liste des enquêtes s’ouvre.
2. Autres contacts : SurveyMars ignore returnUrl et ouvre la page d’accueil du contact.
Remarques importantes
- Conservez la Secret Key sur votre serveur. Ne la placez pas dans la barre d’adresse du navigateur.
- Cette interface connecte un contact. Elle ne crée pas de sous-compte et ne définit pas de rôle de sous-compte.
- Encodage URL des caractères tels que @ dans l’e-mail. Signez la valeur d’origine, pas la valeur encodée.
FAQ
En quoi cela diffère-t-il du SSO des sous-comptes ?
Le SSO des sous-comptes utilise /app/login/sso/verify pour créer ou connecter un sous-compte. La connexion de contact utilise /app/login/contact/verify avec une adresse e-mail ou un identifiant utilisateur tiers. Les champs de signature sont différents. Ne réutilisez pas sign.
Puis-je envoyer uniquement thirdUserId ?
Oui, si le compte principal autorise une adresse e-mail de contact vide. Sinon, email est requis. Utilisez une chaîne vide pour le champ omis dans la signature.
J’ai envoyé à la fois email et thirdUserId. Pourquoi la connexion utilise-t-elle l’e-mail ?
Lorsque les deux sont présents, la vérification ignore thirdUserId et associe le contact par e-mail. thirdUserId est tout de même inclus dans la signature.
Pourquoi un contact qui n’est pas un sous-compte a-t-il ignoré returnUrl ?
returnUrl s’applique uniquement lorsque le contact est un sous-compte. Sinon, SurveyMars l’ignore et ouvre la page d’accueil du contact.
Pourquoi la vérification de la signature échoue-t-elle ?
Vérifiez la Secret Key. Concaténez appId, email, thirdUserId, ts et la Secret Key dans cet ordre. Utilisez une chaîne vide pour un email ou thirdUserId omis. Vérifiez que ts est toujours dans la limite des 60 secondes, et que l’encodage URL n’a pas modifié les valeurs d’origine. N’incluez pas language ni returnUrl.
Pourquoi ts expire-t-il si vite ?
En production, ts doit se situer dans les 60 secondes de l’heure du serveur. Générez ts et sign lorsque l’utilisateur est sur le point d’ouvrir le lien.
