Wenn Sie den Messenger auf Ihrer Website für eingeloggte users installiert haben, ist es wichtig, ihn zu sichern und zu verhindern, dass böswillige Akteure Ihre users imitieren oder unautorisierte Daten senden.
Bei einem nicht gesicherten Messenger könnte jemand mit Ihrem Intercom Messenger interagieren und die Identität eines anderen users vortäuschen, indem er eine bekannte Kennung wie deren E-Mail-Adresse oder user_id angibt. Dies ermöglicht einem Angreifer, sich gegenüber Ihren Teammitgliedern als echter user auszugeben und Zugriff auf vorherige Unterhaltungen und potenziell sensible Daten zu erhalten.
Falls es hilft, hier ist ein Video-Rundgang über die Funktion und die Risiken, die sie mindert:
Wenn Sie eine Messenger-Integration mit eingeloggten users haben, empfehlen wir dringend, Ihren Messenger zu sichern.
Hinweis:
Wenn mehrere users dieselbe E-Mail-Adresse teilen und Ihre Integration nur E-Mail als Kennung verwendet, wird Intercom die Anfrage mit einem Konfliktfehler ablehnen, anstatt zu erraten, welchen user es verwenden soll. Um eine erfolgreiche Authentifizierung sicherzustellen, fügen Sie immer eine stabile eindeutige Kennung (user_id) in Ihre JWT-Nutzlast ein. Beachten Sie, dass die JWT-Identitätsprüfung user_id erfordert; Tokens ohne diese werden abgelehnt.
Was ist ein JSON Web Token (JWT)?
Ein JSON Web Token (JWT) ist ein branchenüblicher Standard zum Signieren von Daten. Es besteht typischerweise aus drei Teilen, getrennt durch Punkte. Ein typisches JWT sieht so aus: header.payload.signature.
Der Header gibt den Token-Typ (JWT) und den Signaturalgorithmus (z. B. HS256) an.
Die Nutzlast enthält Angaben über den user oder die Sitzung (z. B. user_id, E-Mail).
Schließlich stellt die Signatur sicher, dass der Token nicht manipuliert wurde, indem ein geheimer oder privater Schlüssel verwendet wird.
Was sind die Vorteile der Sicherung des Messengers mit JSON Web Tokens (JWTs)?
Sichere user-Identität: Die Sicherung Ihres Messengers ermöglicht es Ihren Teammitgliedern, sicher zu sein, dass der user, mit dem sie sprechen, wirklich dieser user ist.
Erhöhte Sicherheit der user-Daten: Die Sicherung Ihres Messengers ermöglicht die sichere Übertragung von Datenattributen über die Messenger API.
Reduziertes Risiko durch gestohlene Sitzungen: Die Sicherung Ihres Messengers mit JWTs ermöglicht es Ihnen, eine Ablaufzeit für den Token festzulegen, wodurch das Risiko von Datenverletzungen, die durch gestohlene Tokens im Browser des users entstehen könnten, erheblich verringert wird. Durch die Angabe einer kurzen Ablaufzeit wird das Risiko minimiert.
Sicherere Fin- und AI-workflows: Ermöglichen Sie Ihren komplexen Prozessen, Actions und Workflows die Nutzung von Fin, selbst wenn vertrauenswürdige user-Informationen erforderlich sind.
Durch die sichere Übertragung der user-Identität und -Daten sowie die Durchsetzung der Token-Ablaufzeit stellen JWTs sicher, dass Ihr Intercom Messenger im sichersten Zustand ist.
Kundenerlebnis
Bei der Verwendung von JWTs mit dem Intercom Messenger gestaltet sich das Erlebnis wie folgt:
Ihre Messenger-Integration startet Ihren eingeloggten user mit einer
Intercom('boot')-Anfrage, die ein JWT enthält, das alle user-Daten umfasst, die Sie an Intercom senden möchten. Die Signatur des JWT wird mit dem Messenger-Geheimschlüssel aus Ihren Einstellungen generiert.Anschließend stellt Intercom dem user ein Sitzungscookie im Browser bereit. Dieses Cookie hat eine Standarddauer von 7 Tagen. Das Cookie wird während seiner Lebensdauer zur Authentifizierung des users und zur Durchführung von Aktualisierungen verwendet.
Wenn die Sitzung abläuft und kein neues JWT gesendet wird, endet die Sitzung des users. Der user sieht einen frischen Messenger als abgemeldeten Website-Besucher. Dieser enthält nicht die Gesprächshistorie.
Sobald der Messenger mit
Intercom('boot')und einem gültigen JWT neu gestartet wird, identifiziert der Messenger den user und zeigt diesem seine historischen Unterhaltungen sowie eine neue Sitzung an. Zusätzlich werden alle abgemeldeten Aktivitäten, die auf demselben Gerät stattgefunden haben, in das Konto des authentifizierten users zusammengeführt.
Wenn Sie möchten, dass die Lebensdauer des Sitzungscookies des users kürzer als die Standard-7 Tage ist, können Sie die TTL des Cookies in Millisekunden mit dem Messenger-Attribut session_duration angeben.
Installation: Generierung und Versand von JWTs
Schritt 1: Installieren Sie den Messenger in Ihrer Anwendung
Die einzigartigen Einrichtungshinweise für Ihren Workspace finden Sie unter Einstellungen > Messenger > Sicherheit.
Der Hauptunterschied zwischen einer unsicheren Messenger-Konfiguration und einer sicheren besteht darin, dass Sie ein zusätzliches Feld intercomUserJwt in Ihren user-Anfragen einfügen, das zur Identifizierung und Aktualisierung des users verwendet wird.
Sie sehen eine Option, um Datenattribute in Ihr Javascript-Snippet einzufügen. Dies steuert, welche Daten Sie an Intercom senden möchten. Da Sie JWTs zur Datenübertragung verwenden, sollten Sie hier nur Attribute einschließen, die Sie nicht signieren möchten, z. B. wenn Sie einige front-end-spezifische Daten senden wollen.
Wenn Sie keine Daten außerhalb des JWT senden möchten, können Sie alle Daten aus Ihrem Snippet entfernen, außer api_base und app_id. Ihre app_id ist die eindeutige Kennung für Ihren Intercom-Workspace.
Schritt 2: Beginnen Sie mit der Generierung von JWTs für Ihre users
Sie können branchenübliche JWT-Bibliotheken verwenden, um den Token zu generieren, wobei Sie den Messenger API Secret als geheimen Schlüssel verwenden. Ihren geheimen Schlüssel können Sie in den Messenger-Sicherheitseinstellungen Ihres Workspaces generieren.
Wählen Sie Ihre Backend- und Frontend-Frameworks, um relevante Codebeispiele für Ihre Installation zu erhalten.
Hier ist ein Beispiel für Node.js:
Hinweis: Ihre Messenger API-Geheimschlüssel sowie der Code zur Generierung Ihrer JWTs sollten niemals im Frontend-Code verwendet werden. Sie sollten dies immer serverseitig tun und Ihre Geheimschlüssel entsprechend sichern.
Wenn Sie zusätzliche Attribute über Ihre users senden möchten (z. B. price_plan oder number_of_songs_added), fügen Sie diese ebenfalls in Ihr JWT ein. user_id ist das einzige erforderliche Feld. Erfahren Sie hier mehr über benutzerdefinierte Datenattribute.
Wann sollte ich das JWT einfügen?
Sie sollten für jede Anfrage, bei der Sie einen user im Messenger starten oder versuchen, Daten über ihn zu aktualisieren, ein JWT senden.
Welche Ablaufzeit sollte ich setzen?
Setzen Sie eine kurze Ablaufzeit für Ihr JWT, damit es lange genug lebt, um eine vollständige Anfrage zu erreichen und von uns verarbeitet zu werden. Die Ablaufzeit ist kein Pflichtfeld, wird aber dringend empfohlen, um das Risiko von Token-Wiederholungen zu verringern.
Schritt 3: Fügen Sie JWTs in Ihr Messenger-Snippet ein
Beim Starten des Messengers für einen eingeloggten user können Sie ein signiertes JSON Web Token bereitstellen und es dem Attribut intercom_user_jwt der Messenger-Nutzlast zuweisen.
Beispiel für Client-seitige Konfiguration
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "APP_ID_CODE",
intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
};
Dieses JWT kann beliebige user-Datenattribute enthalten, die Sie sicher für den user senden möchten. Sobald ein gültiges JWT für den user empfangen wird, wird im Browser des users ein Sitzungscookie mit einer Standarddauer von 7 Tagen erstellt.
Um die TTL des Messenger-Sitzungscookies zu steuern, können Sie unter Einstellungen > Kanäle > Messenger > Allgemein > Halten Sie Ihren Messenger sicher ein Maximum festlegen.
Schritt 4: Stellen Sie sicher, dass Aktualisierungen für Ihre Attribute deaktiviert sind
Es ist möglich, unsichere Aktualisierungen für Datenattribute der Messenger API zu aktivieren, was bedeutet, dass jede Aktualisierung über den Messenger zur Aktualisierung dieses Attributs erfolgreich ist.
Wenn Sie einige Daten sicher in Ihrem JWT senden, sollten Sie sicherstellen, dass Sie unsichere Messenger-Aktualisierungen für diese Attribute deaktivieren, sodass sie nur über ein gültiges JWT aktualisiert werden. Hinweis: Dieser Schalter verhindert nicht, dass Sie Daten direkt von leads mit einem Bot sammeln.
Wir empfehlen, diesen Schalter für jedes Attribut zu aktivieren, das Sie in Ihrem JWT senden.
Schritt 5: Benutzer-Sitzungen beim Logout beenden
Intercom ermöglicht es Ihnen, den Intercom Messenger auf jeder öffentlichen Website zu platzieren, die Sie besitzen (Ihre Marketingseite, Ihre Dokumentationsseite, Ihr Entwickler-Hub usw.). Um die Kontinuität der Gespräche über all diese potenziell unterschiedlichen Subdomains hinweg zu gewährleisten, während Ihre users eingeloggt sind, setzen wir einen Cookie im Browser Ihres users. Dieser Cookie läuft nach einer Woche ab.
Jeder user, der einen gemeinsam genutzten Computer und Browser mit jemand anderem verwendet, kann die zuletzt angemeldete user-Konversationshistorie sehen, bis der Cookie abläuft. Deshalb ist es sehr wichtig, Intercom ordnungsgemäß zu beenden, wenn die Sitzung eines users in Ihrer App endet (manuell oder automatisch durch Logout).
So beenden Sie Intercom:
Sie haben bereits begonnen, Ihren user über das Intercom JS-Snippet oder die „boot“-Methode zu verfolgen.
Wenn Ihr user sich von Intercom abmeldet (oder automatisch von Ihrer App abgemeldet wird), rufen Sie Intercom('shutdown'); aus unserer JavaScript API auf, um die Intercom-Sitzung zu beenden und den Cookie zu löschen.
🎉 Letzter Schritt: Messenger-Sicherheit für Ihren Workspace durchsetzen
Wenn Ihre Integration JWTs für Ihre users korrekt sendet, sollten Sie die Messenger-Sicherheit aktivieren, indem Sie sie in Ihren Messenger-Einstellungen einschalten. Dadurch verlangt Intercom, dass Anfragen für Ihre Workspace-users entweder mit einem gültigen JWT oder einem gültigen user_hash gesichert sind.
Fehlerbehebungshinweise
Wir haben zwei Tools, die Ihnen bei der Fehlerbehebung Ihrer Installation helfen: eine Möglichkeit, aktuelle Fehlerprotokolle einzusehen, und einen Token-Debugger.
Überprüfen Sie Ihre Installationsprotokolle
Unter Schritt 6 in Einstellungen > Kanäle > Messenger > Sicherheit sehen Sie Ihre Installationsprotokolle. Diese zeigen alle Fehlerprotokolle im Zusammenhang mit Ihrer JWT-Installation. Hier sehen Sie Fehler, die darauf hinweisen, ob Ihre JWTs ungültig, abgelaufen usw. sind. Klicken Sie auf "Protokoll anzeigen", um ein vollständiges Protokoll mit Anfrage-ID, Zeitstempel, Referer und user-Daten zu sehen. Dies kann Ihnen helfen zu verstehen, warum Ihre Anfrage fehlgeschlagen ist, und hilft Ihnen, sie auf Ihre eigene App zurückzuverfolgen.
Häufige Fehlermeldungen
HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": Die Anfrage enthielt sowohl ein JWT als auch einen user_hash. Kunden sollten entweder einen dieser Werte angeben, aber nicht beide.HTTP 400 - „Missing user_id in payload“: Alle JWTs müssen user_id als Teil der Nutzlast enthalten. Wenn ein Kunde „email“ als primären Bezeichner betrachtet, sollte er den E-Mail-Wert sowohl in das user_id- als auch in das email-Feld der Nutzlast einfügen.HTTP 400 - „Invalid intercom_user_jwt payload“: Die JWT-Nutzlast ist ungültig. Kunden sollten sicherstellen, dass die Nutzlast gut geformt, kodiert und mit einem SHA256 HMAC unter Verwendung des api_secret-Werts als Signaturgeheimnis signiert ist.HTTP 400 - „Intercom_user_jwt expired“: Das JWT 'exp' ist ein Zeitstempel in der Vergangenheit. Kunden sollten ein Ablaufdatum in der Zukunft angeben.HTTP 400 - „JWT identity mismatch": Die im JWT angegebene Benutzer-ID stimmt nicht mit dem Benutzer überein, der mit dem aktiven intercom-Sitzungscookie verknüpft ist. Dies deutet darauf hin, dass versucht wird, zwei konkurrierende Sitzungen zu starten. Stellen Sie sicher, dass Sie Intercom('shutdown') aufrufen, bevor Sie versuchen, einen neuen user zu booten.HTTP 400 - "Invalid intercom_user_jwt": Stellen Sie sicher, dass Sie einen gültigen user korrekt booten.
JWT-Decoder
Unser Decoder-Tool bietet Ihnen auch eine Möglichkeit, ein JSON-Web-Token zu überprüfen. Sie finden es in der Seitenleiste auf den Installationsseiten.
Im Tool können Sie eines Ihrer generierten user JWTs auf Gültigkeit prüfen. Wählen Sie den relevanten geheimen Schlüssel, den Sie zur Generierung des JWT verwendet haben, und klicken Sie auf Dekodieren.
Nach dem Dekodieren können Sie die user-Details aus der Nutzlast Ihres JWT, den Header und eine Notiz sehen, ob es gültig oder ungültig ist. Die Anzeige der Nutzlast kann hilfreich sein, um zu überprüfen, ob Sie ein Attribut senden oder nicht.
In diesem Beispiel habe ich sowohl ein ungültiges Geheimnis verwendet als auch das user_id-Feld nicht eingeschlossen, was beide zu einem Fehler führen.
FAQs
Warum ist user_id im JWT erforderlich? Meine users haben nur E-Mail-Adressen.
Sie müssen jetzt user_id als primären Bezeichner für users angeben. Historisch haben wir entweder user_id oder email als mögliche Bezeichner unterstützt, aber das hat zu erheblicher Produktverwirrung bei der grundlegenden Identitätsprüfung geführt.
Wenn Sie nur eine E-Mail zur Identifizierung Ihrer users haben, können Sie die E-Mail-Adresse sowohl im user_id- als auch im email-Attribut der Nutzlast angeben. Wenn Sie Ihre users jedoch bereits nur mit einer E-Mail-Adresse in Intercom haben, müssen Sie diese aktualisieren, um eine user ID zu haben, bevor Sie JWTs verwenden können. Dies liegt daran, dass die user ID ein höherwertiger Bezeichner für users ist als die E-Mail-Adresse.
Um die user ID für Ihre users hinzuzufügen, identifizieren Sie zuerst den user mit der Intercom ID des users. Dies können Sie über unsere API mit dem "Get a contact"-Endpunkt tun. Verwenden Sie dann den "Update a Contact"-Endpunkt, um eine user_id zum user hinzuzufügen. Weitere Details hier
Wie richte ich das für nicht eingeloggte users ein, bei denen ich keine user_id habe?
Die Messenger-Sicherheitsfunktion erfordert, dass Ihre users eindeutige user IDs haben, die Sie bereitstellen. Wenn Sie den Messenger nur für leads verwenden, können Sie diese nicht so identifizieren. Sie sollten sicherstellen, dass die Messenger-APIs für user-Traffic deaktiviert sind, da Sie keinen user-Traffic über diesen Kanal erwarten.
Sie können dies unter Messenger > Installieren tun. Wählen Sie die Installationsmethode, die Sie verwenden (Web, iOS, Android), und prüfen Sie, ob der Schalter „Verbindung zum Messenger aktivieren“ für users aus ist.
Was sollte ich als Ablaufzeit einstellen?
Sie sollten jedes Mal ein neues JWT senden, wenn der Messenger gestartet wird, und die Lebensdauer des Tokens muss nur die Zeit zwischen den Messenger-Starts abdecken. Wählen Sie die minimale Dauer, die für das Verhalten Ihrer Anwendung geeignet ist. Wenn die Webseite oft neu geladen wird, sollte das JWT kurzlebig sein, wir empfehlen jedoch mindestens 5 Minuten, um unerwartete Ablaufprobleme zu vermeiden.
Welchen Signaturalgorithmus kann ich verwenden?
Wir unterstützen HS256 (HMAC mit SHA-256). Dieser Algorithmus verwendet einen gemeinsamen geheimen Schlüssel, um das Token zu signieren und zu verifizieren, wodurch sichergestellt wird, dass die Daten im Token nicht manipuliert wurden.
Kann ich sowohl user_hash als auch intercom_user_jwt senden?
Nein, wir unterstützen nicht das gleichzeitige Senden von user_hash und intercom_user_jwt, da der `user_hash` durch JWTs ersetzt werden sollte. Sie können jedoch zwischen dem Senden von user_hashes und/oder intercom_user_jwt-Werten wechseln, da einige Kunden dies tun müssen, wenn sie von user_hash zu intercom_user_jwt migrieren.
Wenn Sie derzeit Identity Verification verwenden und user hashes senden, sehen Sie sich diese Anleitung an, um Ihre Integration auf das Senden von JWTs umzustellen.
Wie kann ich überprüfen, ob meine JWTs gültig sind und alles funktioniert?
Siehe Abschnitt Fehlerbehebung oben.
Wie setze ich die Anforderung für JWTs in meinem Workspace durch?
Sie sollten den Durchsetzungsschalter in Ihren Messenger-Einstellungen aktivieren.
Welche Attribute sollte ich schützen?
Alle identifizierenden Attribute sollten als geschützt markiert und wenn möglich sicher im JWT gesendet werden. Dazu gehören E-Mail, Telefon und alle account_ids, die der Kunde im User-Datensatz speichern könnte. Sie finden Ihre Attribute unter Einstellungen > Daten > Personen.
Jedes Attribut, das Fin in einem kritischen Teil einer Aktion oder eines Workflows verwenden soll, sollte geschützt sein, um sicherzustellen, dass ein böswilliger user diesen Wert nicht überschreiben kann.
Wenn Sie Daten außerhalb des JWT senden möchten, können Sie das tun, solange Sie Messenger-Updates erlaubt haben, aber bedenken Sie, dass ein user dieses Feld selbst aktualisieren könnte.
window.intercomSettings = {
app_id: <APP_ID_CODE>,
intercom_user_jwt: <TOKEN>,
unsigned_data_attribute: 'data'
};
Was passiert, wenn die Sitzung mitten in einer Aktion des users abläuft?
Wenn nach Ablauf des Cookies Aktivität im Messenger von einem user erfolgt, stellt Intercom einen neuen kurzlebigen Cookie von 1 Stunde aus, um negative Auswirkungen auf die Benutzererfahrung zu vermeiden. Um unbeabsichtigte Effekte auf die Benutzererfahrung zu verhindern, empfehlen wir, eine Sitzungsdauer für den Cookie zu wählen, die mit dem Timeout der Anwendungssitzung übereinstimmt.
Wie sieht es mit meinem mobilen Messenger aus?
Warum verlangen wir nicht, dass die gesamte Nutzlast signiert wird?
Wir erlauben es Kunden, un-signierte Attribute zu senden, um Situationen zu unterstützen, in denen sie niedrigauflösende Daten über den User senden müssen, während der User in ihrer Anwendung aktiv ist. Wenn der Kunde diese Möglichkeit nicht benötigt, kann er alle seine User-Datenattribute auf „geschützt vor Messenger-Updates“ setzen und nur die signierte Nutzlast senden.
Wie verwalte und rotiere ich meine Messenger-Geheimschlüssel?
Ihr Geheimschlüssel kann in den Messenger-Sicherheitseinstellungen Ihres Workspaces generiert werden.
Sie können Ihre vorhandenen Schlüssel in der rechten Seitenleiste der JWT-Einrichtungsseite finden und kopieren.
Sie können Schlüssel in Workspace > Security > Messenger rotieren.
Können Attribute, die in einem JWT enthalten sind, nur für ein einzelnes ticket oder eine einzelne Konversation gelten?
Nein. Alle Attribute, die Sie in einem JSON Web Token (JWT) einschließen, aktualisieren immer das Profil des Users in Intercom. JWT-Attribute können nicht verwendet werden, um Daten hinzuzufügen, die nur für ein einzelnes ticket oder eine einzelne Konversation gelten.
Was ist mit Identity Verification passiert? Ersetzt dies das?
Identity Verification ist die vorherige Version der Messenger-Sicherheit, die mit HMAC-User-Hashes arbeitet, um zu identifizieren, dass eine Benutzeranfrage von Ihrer Integration gesendet wurde.
Während user_hashes weiterhin akzeptiert werden, empfehlen wir allen Kunden dringend, auf JWTs umzusteigen, da diese mehr Sicherheitsvorteile bieten und Identity Verification keine zukünftigen Updates mehr erhalten wird.
Wenn Sie Ihre Identity Verification-Installation von den JWT-Seiten aus verwalten müssen, können Sie dies weiterhin tun. Die Anweisungen wurden aktualisiert, um die JWT-Einrichtung widerzuspiegeln, und wenn Sie Änderungen vornehmen, empfehlen wir dringend, auf JWTs umzusteigen. Wenn Sie die Funktion deaktivieren oder Ihre Messenger API-Geheimschlüssel rotieren müssen, können Sie dies weiterhin über die JWT-Einrichtungsseite erreichen.
Kann ich Firmendaten in meinem JWT einfügen, um users mit einer Firma zu verknüpfen?
Ja. Sie können company_id und andere Firmenattribute in Ihre JWT-Nutzlast einfügen, um users mit einer Firma in Intercom zu verknüpfen. Wenn vorhanden, erstellt und verknüpft Intercom die Firma automatisch beim Booten – genauso wie das Übergeben von Firmendaten in Intercom('boot') funktioniert. Es entsteht keine zusätzliche Latenz, da die Firma inline während der Ping-/Boot-Anfrage erstellt wird.
Dies ist besonders wichtig für Setups, die Firmenfunktionen wie das Tickets Portal verwenden, bei dem tickets, die von mehreren users eingereicht werden, in einer gemeinsamen Firmenansicht zusammengefasst werden müssen. Wenn users nicht mit einer Firma verknüpft werden, überprüfen Sie, ob company_id in Ihrer JWT-Nutzlast enthalten ist.
Alternativ können Sie Firmen erstellen und users über die serverseitige API verknüpfen, bevor sich ein user anmeldet. Dies ist der bessere Ansatz, wenn Firmendaten vor der ersten User-Sitzung existieren müssen – zum Beispiel, um Firmenaufzeichnungen bei der Mandantenerstellung vorab zu befüllen.
Hinweis: Wenn Sie company_id in Ihrem JWT übergeben, aber Firmen in Intercom nicht erstellt werden, wenden Sie sich an unser Support-Team, da dies auf einen bug hinweisen könnte.