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 :
Si vous avez une intégration Messenger avec des users connectés, nous vous recommandons fortement de sécuriser votre Messenger.
Note :
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 : Donnez à vos processus complexes, Actions, et Workflows à Fin, même s'ils nécessitent des informations user fiables.
En transmettant de manière sécurisée l'identité et les données user 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 leur 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 de 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 frais en tant que visiteur du site web déconnecté. Il ne contiendra pas leur historique de conversation.
Une fois que le Messenger est relancé avec
Intercom('boot')et un JWT valide, le Messenger identifiera le user et affichera à l'user ses conversations historiques et une nouvelle session. Nous fusionnerons également toute activité déconnectée 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.
Vous verrez une option pour ajouter des attributs de données dans votre extrait Javascript. Cela régit quelles données vous souhaitez envoyer à Intercom. Puisque vous utiliserez des JWTs pour transmettre des données, vous ne devriez 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 dans les paramètres de sécurité Messenger de votre espace de travail.
Choisissez vos frameworks back et front-end pour obtenir des exemples de code pertinents pour votre installation.
Voici un exemple pour Node.js :
Note : 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 placer 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 durée d'expiration dois-je définir ?
Définissez une courte durée d'expiration 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 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 de l'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 certaines 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'elles ne soient mises à jour que via un JWT valide. Note : ce basculement 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 lors de la déconnexion
Intercom vous permet de placer l'Intercom Messenger 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 Intercom JS 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é du Messenger pour votre espace de travail
Lorsque votre intégration envoie correctement des JWTs pour vos users, vous devez appliquer la sécurité du Messenger en l'activant dans les paramètres du Messenger. Ce faisant, Intercom exigera que les requêtes pour vos users de l'espace de travail soient sécurisées avec un JWT valide ou un user_hash valide.
Guide de dépannage
Nous avons 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 JWTs sont invalides, expirés, etc. Vous cliquez 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'un ou l'autre de ces valeurs, mais pas les deux.HTTP 400 - “Missing user_id in payload”: Tous les JWTs 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 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 pouvez le trouver dans la barre latérale des pages d'installation.
Dans l'outil, vous pouvez vérifier l'un de vos JWTs utilisateur générés pour 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 du user depuis 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 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 provoquera 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é de base.
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 JWTs. 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é du 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 ainsi. Vous devez vous assurer que les API du 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 > Installer. 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 démarrage 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 JWTs. Vous pouvez cependant alterner entre l'envoi de user_hashes 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 JWTs à la place.
Comment vérifier que mes JWTs sont valides et que tout fonctionne ?
Voir la section Dépannage ci-dessus.
Comment appliquer l'exigence des JWTs pour mon espace de travail ?
Vous devez activer le bouton d'application dans les paramètres du 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 tout account_id que le client peut stocker dans le dossier User. Vous pouvez trouver vos attributs dans Paramètres > Données > Personnes.
Tout attribut que vous souhaitez que Fin utilise dans une partie critique d'une Action ou d'un Workflow doit être protégé, pour éviter qu'un user malveillant ne modifie 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 du Messenger, mais gardez à l'esprit qu'un user pourrait lui-même mettre à jour ce champ.
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 d'agir ?
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 ne demandons-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 User 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 peuvent-ils s'appliquer uniquement à un seul ticket ou une seule 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 une seule 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 — de la même manière que le passage des données d'entreprise dans Intercom('boot') fonctionne. Aucune latence supplémentaire n'est introduite, car l'entreprise est créée en ligne pendant la requête ping/boot.
Ceci 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.
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 tenant.
Note : Si vous passez 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.