Les JSON web tokens (JWTs) empêchent les tiers d'usurper l'identité de vos users connectés et de voir leurs conversations. Nous recommandons vivement à tous les clients Fin d'appliquer l'authentification JWT.

Si vous avez installé Fin Messenger 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 Fin 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.

Qu'est-ce qu'un JSON web token (JWT) ?

Un 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 lié aux 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 fuites de données si des tokens sont volés depuis le navigateur de votre user. En spécifiant une expiration courte, 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 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 Fin Messenger est dans l'état le plus sécurisé possible.

Expérience client

Lors de l'utilisation des JWTs avec Fin 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 à votre workspace. La signature du JWT est générée avec la clé secrète Messenger de vos paramètres.
Ensuite, votre workspace fournira à l'user un cookie de session dans son navigateur. Ce cookie a une durée par défaut de 7 jours. Il sera utilisé pendant toute sa durée de vie pour authentifier l'user et effectuer toute mise à jour de cet 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 non connecté sur le site. Il ne contiendra pas son historique de conversation.
Une fois le Messenger relancé avec Intercom('boot') et un JWT valide, le Messenger identifiera l'user et affichera ses conversations historiques ainsi qu'une nouvelle session. Nous fusionnerons également toute activité hors connexion sur le même appareil dans le compte de cet user authentifié.

Conseils :

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.
Si vous créez des tickets Zendesk depuis Fin Messenger et souhaitez que les tickets soient dirigés vers une organisation spécifique, vous pouvez inclure un champ company dans le JWT. La valeur id doit correspondre à l'ID externe de l'organisation Zendesk (et non à l'ID interne Zendesk).

Note : Fin synchronise les réponses des coéquipiers dans Fin pour les conversations web transférées. Cependant, cela ne s'applique pas aux cas Salesforce — une fois qu'un cas est réaffecté à un agent en direct dans Salesforce, Fin cesse de récupérer les mises à jour.

Installation : Génération et envoi des JWTs

Étape 1 : Installer le Messenger dans votre application

Vous pouvez trouver les instructions uniques de configuration pour votre workspace dans Paramètres > Fin 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 intercomUserJwt supplémentaire 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 détermine quelles données vous souhaitez envoyer à votre workspace Fin. Puisque vous utiliserez des JWTs pour transmettre les 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 workspace Fin.

Pour les visiteurs sans identifiants user spécifiques (comme user_id ou email), configurez un extrait Messenger hors connexion en incluant uniquement l'App ID dans votre configuration. Évitez d'ajouter des attributs user pour maintenir une configuration légère et sécurisée pour les visiteurs anonymes.

É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 > Sécurité > Messenger.

Note : Les tokens JWT doivent être générés de manière unique pour chaque session user en utilisant n'importe quelle bibliothèque JWT standard. Les tokens doivent inclure des revendications identifiantes comme user_id et être signés avec le Messenger API Secret pour garantir qu'ils sont associés en toute sécurité au bon user.

Choisissez vos frameworks back et front end pour obtenir des exemples de code pertinents pour votre installation.

Voici un exemple pour Node.js :

Si vous souhaitez envoyer des attributs supplémentaires sur vos users (par exemple : price_plan ou number_of_songs_added), vous devez également les ajouter dans votre JWT. user_id est le seul champ obligatoire. Assurez-vous que les noms de champs dans la charge utile JWT et les attributs respectent la casse. Par exemple, "user_id" doit être écrit avec un "i" minuscule et non "user_Id", car une casse incorrecte peut perturber l'identification correcte de l'user.

Note : Lors de l'utilisation du JWK généré par Fin pour signer les tokens JWT, la revendication sub correspond par défaut à l'ID User attribué par Fin et sert d'identifiant user unique. Cela fournit un mécanisme cohérent et sécurisé pour l'identification user. Avec le mécanisme JWK, la valeur sub est fixe et ne peut pas être personnalisée, garantissant la compatibilité et évitant les erreurs de configuration.

É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. Vous pouvez aussi utiliser Intercom.setUserJwt(jwt) avant de connecter un user pour assigner le token JWT pour une attribution sécurisée des données.

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 de manière sécurisée pour l'user. Une fois qu'un JWT valide est reçu pour l'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 le menu déroulant Gardez votre Messenger sécurisé dans Paramètres > Fin Messenger > Général.

É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 via l'API Messenger, ce qui signifie que toute mise à jour via le Messenger pour 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 non sécurisées du Messenger 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 depuis les leads avec un bot.

Nous vous recommandons d'activer ce bouton pour tout attribut que vous envoyez dans votre JWT.

Étape 5 : Fermez les sessions users à la déconnexion

Vous pouvez installer le Fin 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 le plus récemment connecté jusqu'à l'expiration du cookie. Pour cette raison, il est très important de bien fermer le Fin Messenger lorsque la session d'un user sur votre application se termine (manuellement ou automatiquement via la déconnexion).

Voici comment fermer le Fin Messenger :

Vous avez déjà commencé à suivre votre user via le snippet Intercom JS ou la méthode « boot ».
Lorsque votre user se déconnecte du Fin Messenger (ou est automatiquement déconnecté par votre application), appelez Intercom('shutdown'); depuis notre API JavaScript pour terminer la session 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 JWT pour vos users, vous devez appliquer la sécurité du Messenger en l'activant dans Paramètres > Fin Messenger > Sécurité. Ainsi, le Fin Messenger exigera que les requêtes pour vos users d'espace de travail soient sécurisées avec un JWT valide ou un user_hash valide.

Note : L'authentification JWT est prise en charge à la fois pour le web et le mobile. Le SDK mobile est prêt et pleinement fonctionnel sur l'architecture Bring Your Own Channel — les étapes de configuration dans cet article s'appliquent aux implémentations web et mobile.

Guide de dépannage

Nous disposons de deux outils pour vous aider à déboguer votre installation, un pour 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 > Fin Messenger > Sécurité, vous verrez vos journaux d'installation. Ils 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. 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, 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 champ ‘exp’ du JWT est un horodatage passé. Les clients doivent fournir une date d'expiration future.
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 indique 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.
Si la vérification du token JWT échoue (par exemple, à cause d'une incohérence dans les revendications ou d'une signature incorrecte), la conversation sera automatiquement fermée et une erreur sera enregistrée dans les journaux d'erreurs de l'API pour aider au débogage.

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 sous Paramètres > Messenger > Sécurité.

Dans l'outil, vous pouvez vérifier la validité d'un de vos JWT utilisateur générés. Choisissez la clé secrète pertinente 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 du JWT, l'en-tête et une note indiquant s'il est valide ou invalide.

Dans cet exemple, nous avons utilisé à la fois un secret invalide et je n'ai pas inclus le champ user_id, ce qui provoquera un échec.

FAQ

Pourquoi user_id est-il requis dans le JWT ?

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.

Comment configurer cela pour les users non connectés, lorsque je n'ai pas de user_id ?

La fonction de sécurité du Messenger exige que vos users aient des IDs uniques que vous fournissez. Si vous utilisez le Messenger uniquement pour des leads, vous ne pouvez pas les identifier ainsi. Cependant, si vous avez des users avec des user_ids dans votre espace de travail via une autre intégration (REST API, CSV, etc.), vous devez quand même activer la sécurité JWT du Messenger pour empêcher quelqu'un de tenter de démarrer le Messenger pour ces users. Pour les visiteurs non connectés, vous pouvez configurer le messenger pour fonctionner sans authentification en utilisant une version allégée. Chargez simplement le script du Messenger avec uniquement l'ID de l'application et évitez de passer des données utilisateur ou des tokens JWT. Cela garantit la convivialité tout en maintenant la fonctionnalité du système et l'intégrité des données.

En résumé, si vous avez des users dans votre espace de travail avec des identifiants devinables (email, user_id), vous devez activer la sécurité du Messenger. Pour supporter à la fois les users connectés et non connectés, adoptez une stratégie mixte pour la sécurité et l'utilisabilité. Utilisez l'authentification JWT pour les sessions des users connectés afin de protéger les informations sensibles tout en permettant aux visiteurs non connectés d'utiliser une configuration simplifiée du messenger sans tokens ou données spécifiques à l'utilisateur.

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 inattendue. Incluez toujours une revendication d'expiration (exp) dans vos JWT pour assurer la sécurité en réduisant l'impact des tokens volés.

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.
RS256 pour les JWT, qui utilise une paire de clés asymétriques - privée pour la signature et publique pour la vérification, offrant une alternative pour une sécurité renforcée.
Configurations JSON Web Key (JWK), qui permettent une intégration fluide avec les clés générées par Fin pour une gestion simplifiée des tokens.

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 doit ê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.

Comment 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 tout account_id que le client peut stocker dans l'enregistrement User. Vous pouvez trouver vos attributs dans Paramètres > Données des 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 utilisateur 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 modifier 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 de faire quelque chose ?

S'il y a une activité dans le Messenger d'un user après l'expiration du cookie, un nouveau cookie à courte durée de vie d'une heure sera émis pour éviter un impact négatif sur l'expérience utilisateur. Pour éviter tout effet indésirable, nous vous recommandons de choisir une durée de session du cookie qui correspond à celle du timeout de session de votre application.

Pourquoi ne demandons-nous pas que la charge utile complète soit signée ?

Nous vous permettons d'envoyer des attributs non signés pour prendre en charge les situations où vous devez envoyer des données à faible fidélité sur l'utilisateur, pendant que l'utilisateur agit dans votre application. Si vous n'avez pas besoin de cette capacité, vous pouvez mettre à jour tous vos 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 Paramètres > Sécurité > Messenger.

Qu'est-il arrivé à la vérification d'identité ? Les JWT la remplacent-ils ?

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 continuent d'être acceptés, nous recommandons fortement à tous les clients de passer aux JWT car ils offrent 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 Paramètres > Sécurité > Messenger.

Puis-je inclure des données d'entreprise dans mon JWT pour associer des users à une entreprise ?

Oui. Incluez company_id et d'autres attributs d'entreprise dans la charge utile de votre JWT pour associer des users à une entreprise. Cela créera et associera automatiquement l'entreprise au démarrage, sans latence supplémentaire.

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.

Authentification des users dans Fin Messenger avec des JSON web tokens (JWTs)