Si vous avez le Messenger installé sur votre site pour les users connectés, il est essentiel de le sécuriser et d'empêcher les acteurs malveillants d'usurper l'identité de vos users ou d'envoyer des données non autorisées.
Sur un Messenger non sécurisé, quelqu'un pourrait interagir avec votre Intercom Messenger et usurper l'identité d'un autre user, en fournissant un identifiant connu comme leur adresse email ou user_id. Cela permet à un attaquant de se faire passer pour un vrai user auprès de vos coéquipiers, donnant accès aux conversations précédentes et potentiellement à des données sensibles.
Si cela peut aider, voici une vidéo explicative de la fonctionnalité et des risques qu'elle atténue :
Note :
Si vous avez une intégration Messenger avec des users connectés, nous vous recommandons fortement de sécuriser votre Messenger.
Si plusieurs users partagent la même adresse email et que votre intégration utilise uniquement l'email comme identifiant, Intercom rejette la requête avec une erreur de conflit plutôt que de deviner quel user utiliser. Pour garantir une authentification réussie, incluez toujours un identifiant unique stable (user_id) dans la charge utile de votre JWT. Notez que la vérification d'identité JWT exige user_id, les tokens sans celui-ci seront rejetés.
Qu'est-ce qu'un JSON web token (JWT) ?
Un JSON Web Token (JWT) est une méthode standard de l'industrie pour signer des données. Il se compose généralement de trois parties, séparées par des points. Un JWT typique ressemble à ceci : header.payload.signature.
L'en-tête spécifie le type de token (JWT) et l'algorithme de signature (par exemple, HS256).
La charge utile contient des revendications sur le user ou la session (par exemple, user_id, email).
Enfin, la signature garantit que le token n'a pas été altéré, en utilisant une clé secrète ou privée.
Quels sont les avantages de sécuriser le Messenger avec des JSON web tokens (JWTs) ?
Identité user sécurisée : Sécuriser votre messenger permet à vos coéquipiers d'être sûrs que le user avec qui ils parlent est bien ce user.
Sécurité renforcée des données user : Sécuriser votre Messenger permet la transmission sécurisée des attributs de données concernant votre user via l'API Messenger.
Risque réduit de sessions volées : Sécuriser votre Messenger avec des JWTs vous permet de définir une expiration pour le token, réduisant significativement le risque de violations de données pouvant survenir si des tokens sont volés depuis le navigateur de votre user. En spécifiant une courte expiration, le risque est diminué.
Workflows Fin et AI plus sûrs : Confiez vos processus complexes, Actions, et Workflows à Fin, même s'ils nécessitent des informations fiables sur le user.
Astuce : Activer la sécurité du Messenger débloque également l'historique complet des conversations de vos users dans le Messenger. Sans cela, les users connectés ne peuvent voir que les conversations des 14 derniers jours — une mesure de sécurité pour empêcher l'accès non autorisé. Une fois la sécurité du Messenger activée sur un canal, la limite d'historique est automatiquement supprimée. Voir Visibilité de l'historique des conversations utilisateur pour plus de détails.
En transmettant de manière sécurisée l'identité et les données des users et en appliquant l'expiration des tokens, les JWTs garantissent que votre Intercom Messenger est dans l'état le plus sécurisé possible.
Expérience client
Lors de l'utilisation des JWTs avec l'Intercom Messenger, l'expérience est la suivante :
Votre intégration Messenger lancera votre user connecté avec une requête
Intercom('boot')contenant un JWT, qui inclut toutes les données user que vous souhaitez envoyer à Intercom. La signature du JWT est générée en utilisant la clé secrète Messenger de vos paramètres.Ensuite, Intercom fournira à l'user un cookie de session dans son navigateur. Ce cookie a une durée par défaut de 7 jours. Le cookie sera utilisé pendant toute sa durée de vie pour authentifier le user et effectuer toute mise à jour concernant ce user.
Si la session expire et qu'aucun nouveau JWT n'est envoyé, la session de l'user prendra fin. L'user verra un Messenger neuf en tant que visiteur du site web déconnecté. Il ne contiendra pas leur historique de conversation.
Une fois le Messenger relancé avec
Intercom('boot')et un JWT valide, le Messenger identifiera le user et affichera ses conversations historiques ainsi qu'une nouvelle session. Nous fusionnerons également toute activité hors ligne survenue sur le même appareil dans le compte de ce user authentifié.
Si vous souhaitez que la durée de vie du cookie de session de l'user soit plus courte que les 7 jours par défaut, vous pouvez spécifier le TTL du cookie en millisecondes avec l'attribut session_duration du Messenger.
Installation : Génération et envoi des JWTs
Étape 1 : Installez le Messenger dans votre application
Vous pouvez trouver les instructions d'installation uniques pour votre espace de travail dans Paramètres > Messenger > Sécurité.
La principale différence entre une configuration Messenger non sécurisée et une configuration sécurisée est que vous inclurez un champ supplémentaire intercomUserJwt dans vos requêtes user, qui sera utilisé pour identifier et mettre à jour le user.
Note : Vous verrez une option pour ajouter des attributs de données dans votre extrait Javascript. Cela régit les données que vous souhaitez envoyer à Intercom. Puisque vous utiliserez des JWTs pour transmettre des données, vous ne devez inclure ici que les attributs que vous ne souhaitez pas signer, par exemple : si vous voulez envoyer des données spécifiques au front-end.
Si vous ne souhaitez envoyer aucune donnée en dehors du JWT, vous pouvez supprimer toutes les données de votre extrait sauf api_base et app_id. Votre app_id est l'identifiant unique de votre espace de travail Intercom.
Étape 2 : Commencez à générer des JWTs pour vos users
Vous pouvez utiliser des bibliothèques JWT standard de l'industrie pour générer le token, en utilisant le Messenger API Secret comme clé secrète. Votre clé secrète peut être générée depuis Paramètres > Espace de travail > Sécurité > Messenger.
Puis revenez aux paramètres Messenger > Sécurité et choisissez vos frameworks back et front end pour obtenir des exemples de code pertinents pour votre installation.
Voici un exemple pour Node.js :
Important : Vos clés secrètes API Messenger ainsi que le code pour générer vos JWTs ne doivent jamais être placés dans le code front-end. Vous devez toujours les mettre côté serveur et sécuriser vos clés secrètes en conséquence.
S'il y a des attributs supplémentaires que vous souhaitez envoyer à propos de vos users (par exemple : price_plan ou number_of_songs_added), vous les ajouterez également dans votre JWT. user_id est le seul champ obligatoire. En savoir plus sur les attributs de données personnalisés ici.
Quand dois-je inclure le JWT ?
Vous devez envoyer un JWT pour chaque requête où vous démarrez un user dans le Messenger ou essayez de mettre à jour des données à son sujet.
Quelle expiration dois-je définir ?
Définissez une expiration courte pour votre JWT, en vous assurant qu'il vit assez longtemps pour qu'une requête complète nous parvienne et soit traitée. L'expiration n'est pas un champ obligatoire mais fortement recommandée pour réduire le risque de rejouage de token.
Étape 3 : Ajoutez les JWTs à votre extrait Messenger
Lors du lancement du Messenger pour un user connecté, vous pouvez fournir un JSON Web Token signé et l'assigner à l'attribut intercom_user_jwt de la charge utile du Messenger.
Exemple de configuration côté client :
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "APP_ID_CODE",
intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
};
Ce JWT peut contenir tous les attributs de données user que vous souhaitez envoyer en toute sécurité pour le user. Une fois qu'un JWT valide est reçu pour le user, un cookie de session sera créé dans le navigateur du user avec une durée par défaut de 7 jours.
Pour contrôler le TTL du cookie de session Messenger, vous pouvez définir un maximum dans Paramètres > Canaux > Messenger > Général > Gardez votre Messenger sécurisé
Étape 4 : Assurez-vous que les mises à jour sont désactivées pour vos attributs
Il est possible d'activer des mises à jour non sécurisées pour les attributs de données de l'API Messenger, ce qui signifie que toute mise à jour via le Messenger pour modifier cet attribut réussira.
Si vous envoyez des données de manière sécurisée dans votre JWT, vous devez vous assurer de désactiver les mises à jour Messenger non sécurisées pour ces attributs afin qu'ils ne soient mis à jour que via un JWT valide. Note : ce bouton ne vous empêche pas de collecter des données directement auprès des leads avec un bot
Nous vous recommandons d'activer ce bouton pour tout attribut que vous envoyez dans votre JWT.
Étape 5 : Fermer les sessions utilisateur à la déconnexion
Intercom vous permet de mettre le Messenger Intercom sur n'importe quel site public que vous possédez (votre site marketing, votre site de documentation, votre hub développeur, etc.). Pour maintenir la continuité des conversations sur tous ces sous-domaines potentiellement différents pendant que vos users sont connectés, nous plaçons un cookie dans le navigateur de votre user. Ce cookie expire après une semaine.
Tout user qui utilise un ordinateur et un navigateur partagés avec quelqu'un d'autre pourra voir l'historique des conversations du user connecté le plus récemment jusqu'à l'expiration du cookie. Pour cette raison, il est très important de bien fermer Intercom lorsque la session d'un user sur votre application se termine (via une déconnexion manuelle ou automatique).
Voici comment fermer Intercom :
Vous avez déjà commencé à suivre votre user via le snippet JS Intercom ou la méthode « boot ».
Lorsque votre user se déconnecte d'Intercom (ou est automatiquement déconnecté par votre application), appelez Intercom('shutdown'); depuis notre API JavaScript, pour terminer la session Intercom et effacer le cookie.
Dernière étape : Appliquer la sécurité Messenger pour votre espace de travail
Lorsque votre intégration envoie correctement des JWT pour vos users, vous devez appliquer la sécurité Messenger en l'activant dans Paramètres Messenger > Sécurité. En faisant cela, Intercom exigera que les requêtes pour vos users de l'espace de travail soient sécurisées avec soit un JWT valide, soit un user_hash valide.
Guide de dépannage
Nous disposons de deux outils pour vous aider à déboguer votre installation, un moyen de voir les journaux d'erreurs récents et un débogueur de token.
Vérifiez vos journaux d'installation
À l'étape 6 sous Paramètres > Canaux > Messenger > Sécurité, vous verrez vos journaux d'installation. Ceux-ci afficheront tous les journaux d'échec liés à votre installation JWT. Vous y verrez des erreurs indiquant si vos JWT sont invalides, expirés, etc. Vous pouvez cliquer sur « Voir le journal » pour voir un journal complet incluant l'ID de la requête, l'horodatage, le référent et les données utilisateur. Cela peut vous aider à comprendre pourquoi votre requête a échoué et à la retracer jusqu'à votre propre application.
Messages d'erreur courants
HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": La requête incluait à la fois un JWT et un user_hash. Les clients doivent inclure l'une de ces valeurs, mais pas les deux.HTTP 400 - “Missing user_id in payload”: Tous les JWT doivent inclure user_id dans la charge utile. Si un client considère « email » comme son identifiant principal, il doit mettre la valeur email à la fois dans les champs user_id et email de la charge utile.HTTP 400 - “Invalid intercom_user_jwt payload”: La charge utile du JWT est invalide. Les clients doivent s'assurer que la charge utile est bien formée, encodée et signée avec un HMAC SHA256 en utilisant la valeur api_secret comme secret de signature.HTTP 400 - “Intercom_user_jwt expired”: Le ‘exp’ du JWT est un horodatage passé. Les clients doivent fournir une date d'expiration dans le futur.HTTP 400 - “JWT identity mismatch": L'ID utilisateur fourni dans le JWT ne correspond pas à l'utilisateur associé au cookie de session intercom actif. Cela indiquerait qu'il y a une tentative de démarrer deux sessions concurrentes. Assurez-vous d'appeler Intercom('shutdown') avant de tenter de démarrer un nouvel user.HTTP 400 - "Invalid intercom_user_jwt": Assurez-vous de bien démarrer un user valide.
Décodeur JWT
Notre outil de décodage vous permet également de vérifier un JSON web token. Vous le trouverez dans la barre latérale des pages d'installation.
Dans l'outil, vous pouvez vérifier l'un de vos JWT utilisateur générés pour sa validité. Choisissez la clé secrète pertinente que vous avez utilisée pour générer le JWT et cliquez sur Décoder.
Une fois décodé, vous pouvez voir les détails de l'utilisateur dans la charge utile de votre JWT, l'en-tête et une note indiquant s'il est valide ou non. Voir la charge utile peut être utile pour aider à dépanner si vous envoyez un attribut ou non.
Dans cet exemple, j'ai utilisé à la fois un secret invalide et je n'inclus pas le champ user_id, ce qui entraînera un échec.
FAQ
Pourquoi user_id est-il requis dans le JWT ? Mes users n'ont que des adresses email.
Vous devez désormais fournir user_id comme identifiant principal pour les users. Historiquement, nous avons supporté soit user_id soit email comme identifiants potentiels, mais cela a créé une confusion importante dans la vérification d'identité basique.
Si vous n'avez qu'un email pour identifier vos users, vous pouvez fournir l'adresse email à la fois dans les attributs user_id et email de la charge utile. Cependant, si vous avez déjà vos users dans Intercom avec seulement une adresse email, vous devrez les mettre à jour pour qu'ils aient un user ID avant de pouvoir utiliser les JWT. En effet, le user ID est un identifiant de niveau supérieur aux adresses email.
Pour ajouter un user ID à vos users, identifiez d'abord le user avec l’ID Intercom de l'utilisateur. Vous pouvez le faire via notre API avec le point de terminaison « Get a contact ». Ensuite, utilisez le point de terminaison « Update a Contact » pour ajouter un user_id à l'utilisateur. Plus de détails ici
Comment configurer cela pour les users non connectés, lorsque je n'ai pas de user_id ?
La fonctionnalité de sécurité Messenger exige que vos users aient des user IDs uniques que vous fournissez. Si vous utilisez le Messenger uniquement pour des leads, vous ne pouvez pas les identifier de cette manière. Vous devez vous assurer que les API Messenger sont désactivées pour le trafic utilisateur, car vous n'attendez pas de trafic utilisateur via ce canal.
Vous pouvez faire cela dans Messenger > Install. Choisissez la méthode d'installation que vous utilisez (web, iOS, Android) et vérifiez que le bouton « Activer la connexion au messenger » est désactivé pour les users.
Quelle durée d'expiration dois-je définir ?
Vous devez envoyer un nouveau JWT à chaque lancement du Messenger, donc la durée de vie du token doit seulement couvrir la période entre les lancements du Messenger. Choisissez la durée minimale adaptée au comportement de votre application. Si la page web est souvent rechargée, le JWT doit être de courte durée, bien que nous suggérions un minimum de 5 minutes pour éviter des problèmes d'expiration inattendus.
Quel algorithme de signature puis-je utiliser ?
Nous supportons HS256 (HMAC avec SHA-256). Cet algorithme utilise une clé secrète partagée pour signer et vérifier le token, garantissant que les données dans le token n'ont pas été altérées.
Puis-je envoyer à la fois un user_hash et un intercom_user_jwt ?
Non, nous ne supportons pas l'envoi simultané de user_hash et intercom_user_jwt, car le `user_hash` devrait être remplacé par les JWT. Vous pouvez cependant alterner entre l'envoi de user_hash et/ou de valeurs intercom_user_jwt, car certains clients doivent le faire lors de la migration de user_hash vers intercom_user_jwt.
Si vous utilisez actuellement la vérification d'identité et envoyez des user hashes, consultez ce guide pour changer votre intégration afin d'envoyer des JWT à la place.
Comment puis-je vérifier que mes JWT sont valides et que tout fonctionne ?
Voir la section Dépannage ci-dessus.
Comment appliquer l'exigence des JWT pour mon espace de travail ?
Vous devez activer le bouton d'application dans les paramètres de votre Messenger.
Quels attributs dois-je protéger ?
Tous les attributs d'identification doivent être marqués comme protégés et envoyés de manière sécurisée dans le JWT si possible. Cela inclut email, téléphone, et tous les account_ids que le client peut stocker dans le dossier User. Vous pouvez trouver vos attributs dans Paramètres > Données > People.
Tout attribut que vous souhaitez que Fin utilise dans une partie critique d'une Action ou d'un Workflow doit être protégé, pour garantir qu'un user malveillant ne puisse pas remplacer cette valeur.
Si vous souhaitez envoyer des données en dehors du JWT, vous pouvez le faire tant que vous avez autorisé les mises à jour Messenger, mais gardez à l'esprit qu'un user pourrait mettre à jour ce champ lui-même.
window.intercomSettings = {
app_id: <APP_ID_CODE>,
intercom_user_jwt: <TOKEN>,
unsigned_data_attribute: 'data'
};
Que se passe-t-il si la session expire alors que l'utilisateur est en train de faire quelque chose ?
S'il y a une activité dans le Messenger de la part d'un user après l'expiration du cookie, Intercom émettra un nouveau cookie à courte durée de vie d'une heure pour éviter un impact négatif sur l'expérience utilisateur. Pour éviter tout effet indésirable sur l'expérience utilisateur, nous vous recommandons de choisir une durée de session du cookie qui correspond à celle du timeout de session de votre application.
Qu'en est-il de mon Messenger mobile ?
Pourquoi n'exigeons-nous pas que la charge utile complète soit signée ?
Nous permettons aux clients d'envoyer des Attributs non signés pour soutenir les situations où ils doivent envoyer des données à faible fidélité sur l'User, pendant que l'User agit dans leur application. Si le client n'a pas besoin de cette capacité, il peut mettre à jour tous ses Attributs de Données Utilisateur pour qu'ils soient « protégés contre les mises à jour Messenger » et n'envoyer que la charge utile signée.
Comment gérer et faire pivoter mes clés secrètes Messenger ?
Votre clé secrète peut être générée dans les paramètres de sécurité Messenger de votre workspace.
Vous pouvez trouver et copier vos clés existantes dans la barre latérale droite de la page de configuration JWT.
Vous pouvez faire pivoter les clés dans Workspace > Security > Messenger.
Les attributs inclus dans un JWT ne peuvent-ils s'appliquer qu'à un seul ticket ou conversation ?
Non. Tous les attributs que vous incluez dans un JSON Web Token (JWT) mettront toujours à jour le profil de l'utilisateur dans Intercom. Les attributs JWT ne peuvent pas être utilisés pour ajouter des données qui s'appliquent uniquement à un seul ticket ou conversation.
Que s'est-il passé avec la Vérification d'Identité ? Est-ce que cela la remplace ?
La Vérification d'Identité est l'itération précédente de la Sécurité Messenger qui fonctionne en utilisant des hachages utilisateur HMAC pour identifier qu'une requête utilisateur a été envoyée par votre intégration.
Bien que les user_hashes continueront d'être acceptés, nous recommandons fortement à tous les clients de passer à l'utilisation des JWT car cela offre plus d'avantages en matière de sécurité et la Vérification d'Identité ne recevra plus de mises à jour futures.
Si vous devez gérer votre installation de Vérification d'Identité depuis les pages JWT, vous pouvez toujours le faire. Les instructions ont été mises à jour pour refléter la configuration JWT, et si vous effectuez des modifications, nous vous recommandons fortement de passer aux JWT, mais si vous devez désactiver la fonctionnalité ou faire pivoter vos clés secrètes Messenger API, vous pouvez toujours le faire depuis la page de configuration JWT.
Puis-je inclure des données d'entreprise dans mon JWT pour associer des users à une entreprise ?
Oui. Vous pouvez inclure company_id et d'autres attributs d'entreprise dans la charge utile de votre JWT pour associer des users à une entreprise dans Intercom. Lorsqu'ils sont présents, Intercom créera et associera automatiquement l'entreprise au démarrage (aucune latence supplémentaire n'est introduite, car l'entreprise est créée en ligne pendant la requête ping/boot).
C'est particulièrement important pour les configurations qui utilisent des fonctionnalités au niveau de l'entreprise telles que le Tickets Portal, où les tickets soumis par plusieurs users doivent être regroupés dans une vue d'entreprise partagée. Si les users ne sont pas associés à une entreprise, vérifiez que company_id est inclus dans la charge utile de votre JWT.
Important : Les données d'entreprise transmises en dehors du JWT (par exemple, en tant qu'objet company dans votre appel Intercom('boot')) sont ignorées lorsqu'un JWT est présent. L'entreprise ne sera pas mise à jour, et la valeur last_seen de l'entreprise ne sera pas rafraîchie. Pour garantir que les données d'entreprise soient mises à jour correctement, incluez-les dans la charge utile de votre JWT. C'est l'approche recommandée pour toutes les configurations Messenger sécurisées.
Alternativement, vous pouvez créer des entreprises et associer des users via l'API côté serveur avant que tout user ne se connecte. C'est la meilleure approche lorsque vous avez besoin que les données d'entreprise existent avant la première session utilisateur — par exemple, pour pré-remplir les enregistrements d'entreprise lors de la création du locataire.
Note : Si vous transmettez company_id dans votre JWT mais que les entreprises ne sont pas créées dans Intercom, signalez-le à notre équipe de support car cela peut indiquer un bug.