JSON-Web-Tokens (JWTs) verhindern, dass Dritte Ihre angemeldeten users imitieren und deren Unterhaltungen einsehen. Wir empfehlen allen Fin-Kunden dringend, die JWT-Authentifizierung durchzusetzen.
Wenn Sie den Fin Messenger auf Ihrer Website für angemeldete users installiert haben, ist es unerlässlich, 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 Fin 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, wodurch er Zugang zu vorherigen Unterhaltungen und potenziell sensiblen Daten erhält.
Was ist ein JSON-Web-Token (JWT)?
Ein JWT ist ein branchenüblicher Standard zur Signierung 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 Payload enthält Angaben über den user oder die session (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 Benutzeridentitä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 Benutzerdaten: Die Sicherung Ihres Messengers ermöglicht die sichere Übertragung von Datenattributen über die Messenger API über Ihren user.
Reduziertes Risiko durch gestohlene sessions: 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 aus dem Browser Ihres users entstehen könnten, erheblich reduziert wird. Durch die Festlegung einer kurzen Ablaufzeit wird das Risiko verringert.
Sicherere Fin- und AI-Workflows: Übergeben Sie Ihre komplexen Prozesse, Aktionen und Workflows an Fin, auch wenn sie vertrauenswürdige Benutzerinformationen erfordern.
Durch die sichere Übertragung der Benutzeridentität und -daten sowie die Durchsetzung der Token-Ablaufzeit stellen JWTs sicher, dass Ihr Fin Messenger im höchstmöglichen Sicherheitszustand ist.
Kundenerfahrung
Bei der Verwendung von JWTs mit dem Fin Messenger gestaltet sich die Erfahrung wie folgt:
Ihre Messenger-Integration startet Ihren angemeldeten user mit einer
Intercom('boot')-Anfrage, die ein JWT enthält, das alle Benutzerdaten umfasst, die Sie an Ihren Workspace senden möchten. Die Signatur des JWT wird mit dem Messenger-Geheimschlüssel aus Ihren Einstellungen generiert.Anschließend stellt Ihr Workspace 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 session abläuft und kein neues JWT gesendet wird, endet die user session. Der user sieht einen frischen Messenger als ausgeloggter 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 session an. Zusätzlich werden alle ausgeloggten Aktivitäten, die auf demselben Gerät stattgefunden haben, in das Konto des authentifizierten users zusammengeführt.
Tipps:
Wenn Sie möchten, dass die Lebensdauer des user session cookies kürzer als die Standard-7 Tage ist, können Sie die TTL des Cookies in Millisekunden mit dem session_duration Messenger-Attribut angeben.
Wenn Sie Zendesk tickets aus dem Fin Messenger erstellen und tickets an eine bestimmte Organisation weiterleiten möchten, können Sie ein Firmenfeld im JWT einfügen. Der
id-Wert sollte mit der externen ID der Zendesk-Organisation übereinstimmen (nicht mit der internen Zendesk-ID).
Hinweis: Fin synchronisiert Teamantworten in Fin für Webgespräche, die übergeben werden. Dies gilt jedoch nicht für Salesforce-Fälle – sobald ein Fall einem Live-Agenten in Salesforce zugewiesen wird, zieht Fin keine Updates mehr.
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 > Fin Messenger > Sicherheit.
Der Hauptunterschied zwischen einer unsicheren Messenger-Konfiguration und einer sicheren besteht darin, dass Sie ein zusätzliches intercomUserJwt-Feld in Ihren Benutzeranfragen einfügen, das zur Identifizierung und Aktualisierung des users verwendet wird.
Sie sehen eine Option, Datenattribute in Ihr Javascript-Snippet einzufügen. Dies steuert, welche Daten Sie an Ihren Fin Workspace 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 Fin Workspace.
Für Besucher ohne benutzerspezifische Kennungen (wie user_id oder E-Mail) konfigurieren Sie ein ausgeloggtes Messenger-Snippet, indem Sie nur die App-ID in Ihrer Einrichtung angeben. Vermeiden Sie das Hinzufügen von Benutzerattributen, um eine leichte, sichere Konfiguration für anonyme Besucher zu gewährleisten.
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 unter Einstellungen > Sicherheit > Messenger generieren.
Hinweis: JWT-Tokens müssen für jede user session eindeutig mit einer beliebigen Standard-JWT-Bibliothek generiert werden. Tokens müssen identifizierende Angaben wie user_id enthalten und mit dem Messenger API Secret signiert sein, um sicherzustellen, dass sie sicher mit dem richtigen user verknüpft sind.
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:
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. Achten Sie darauf, dass die Feldnamen innerhalb der JWT-Payload und der Attribute case-sensitiv sind. Zum Beispiel muss "user_id" mit einem kleinen "i" geschrieben werden, nicht "user_Id", da falsche Groß-/Kleinschreibung die korrekte Benutzeridentifikation stören kann.
Hinweis: Bei Verwendung des von Fin generierten JWK zur Signierung von JWT-Tokens ist der sub-Anspruch standardmäßig die von Fin vergebene User-ID und dient als eindeutiger Benutzeridentifikator. Dies bietet einen konsistenten und sicheren Mechanismus zur Benutzeridentifikation. Bei Verwendung des JWK-Mechanismus ist der sub-Wert fest und kann nicht angepasst werden, was die Kompatibilität sicherstellt und Fehlkonfigurationen verhindert.
Schritt 3: Fügen Sie JWTs Ihrem Messenger-Snippet hinzu
Beim Starten des Messengers für einen angemeldeten user können Sie ein signiertes JSON-Web-Token bereitstellen und es dem intercom_user_jwt-Attribut der Messenger-Payload zuweisen. Alternativ können Sie auch Intercom.setUserJwt(jwt) verwenden, bevor Sie einen user anmelden, um den JWT-Token für eine sichere Datenzuordnung zuzuweisen.
Beispiel für die 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 Benutzerdatenattribute 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-Session-Cookies zu steuern, können Sie unter dem Dropdown-Menü "Keep your Messenger secure" in Einstellungen > Fin Messenger > Allgemein ein Maximum festlegen.
Schritt 4: Stellen Sie sicher, dass Updates für Ihre Attribute deaktiviert sind
Es ist möglich, unsichere Updates für Datenattribute der Messenger API zu aktivieren, was bedeutet, dass jede Aktualisierung über den Messenger für dieses Attribut erfolgreich ist.
Wenn Sie einige Daten sicher in Ihrem JWT senden, sollten Sie sicherstellen, dass Sie unsichere Messenger-Updates 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 alle Attribute zu aktivieren, die Sie in Ihrem JWT senden.
Schritt 5: Beenden Sie user sessions beim Logout
Sie können den Fin Messenger auf jeder öffentlich zugänglichen Website installieren, die Sie besitzen (Ihre Marketingseite, Ihre Dokumentationsseite, Ihr Entwickler-Hub usw.). Um die Kontinuität der Gespräche über all diese möglicherweise unterschiedlichen Subdomains hinweg zu gewährleisten, während Ihre users eingeloggt sind, setzen wir ein Cookie im Browser Ihres users. Dieses Cookie läuft nach einer Woche ab.
Jeder user, der einen gemeinsam genutzten Computer und Browser mit jemand anderem verwendet, kann die zuletzt angemeldete Konversationshistorie sehen, bis das Cookie abläuft. Deshalb ist es sehr wichtig, den Fin Messenger ordnungsgemäß zu schließen, wenn die Sitzung eines users in Ihrer App endet (manuell oder automatisch ausgeloggt).
So schließen Sie den Fin Messenger:
Sie haben bereits begonnen, Ihren user über das Intercom JS-Snippet oder die „boot“-Methode zu verfolgen.
Wenn sich Ihr user vom Fin Messenger abmeldet (oder automatisch von Ihrer App abgemeldet wird), rufen Sie Intercom('shutdown'); aus unserer JavaScript API auf, um die Sitzung zu beenden und das Cookie zu löschen.
Letzter Schritt: Erzwingen Sie die Messenger-Sicherheit für Ihren Workspace
Wenn Ihre Integration JWTs für Ihre users korrekt sendet, sollten Sie die Messenger-Sicherheit aktivieren, indem Sie sie unter Einstellungen > Fin Messenger > Sicherheit einschalten. Dadurch verlangt der Fin Messenger, dass Anfragen für Ihre Workspace-users entweder mit einem gültigen JWT oder einem gültigen user_hash gesichert sind.
Hinweis: JWT-Authentifizierung wird sowohl für Web als auch Mobile unterstützt. Das Mobile SDK ist bereit und voll funktionsfähig auf der Bring Your Own Channel-Architektur – die Einrichtungsschritte in diesem Artikel gelten für Web- und Mobile-Implementierungen.
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 > Fin 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 Benutzerdaten zu sehen. Dies kann Ihnen helfen zu verstehen, warum Ihre Anfrage fehlgeschlagen ist, und es erleichtert die Rückverfolgung zu Ihrer eigenen App.
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 verwendet, 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 korrekt formatiert, kodiert und mit einem SHA256 HMAC unter Verwendung des api_secret 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 starten.HTTP 400 - "Invalid intercom_user_jwt": Stellen Sie sicher, dass Sie einen gültigen user korrekt starten.Wenn die JWT-Token-Überprüfung fehlschlägt (z. B. wegen eines Anspruchsfehlers oder unsachgemäßer Signierung), wird das Gespräch automatisch geschlossen und ein Fehler in den API-Fehlerprotokollen protokolliert, um bei der Fehlerbehebung zu helfen.
JWT-Decoder
Unser Decoder-Tool bietet Ihnen auch eine Möglichkeit, ein JSON-Web-Token zu überprüfen. Sie finden es in der Seitenleiste unter Einstellungen > Messenger > Sicherheit.
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 Decode.
Nach der Dekodierung sehen Sie die Benutzerdetails aus der Nutzlast Ihres JWT, den Header und eine Notiz, ob es gültig oder ungültig ist.
In diesem Beispiel haben wir 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?
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, was jedoch zu erheblicher Produktverwirrung bei der grundlegenden Identitätsprüfung geführt hat. 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.
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. Wenn Sie jedoch users mit user_ids in Ihrem Workspace aus einer anderen Integration (REST API, CSV usw.) haben, sollten Sie die JWT Messenger-Sicherheit trotzdem aktivieren, um zu verhindern, dass jemand versucht, den Messenger für diese users zu starten. Für ausgeloggte Besucher können Sie den Messenger so konfigurieren, dass er ohne Authentifizierung funktioniert, indem Sie eine leichte Version verwenden. Laden Sie einfach das Messenger-Skript nur mit der App-ID und übergeben Sie keine Benutzerdaten oder JWT-Tokens. Dies gewährleistet Benutzerfreundlichkeit bei gleichzeitiger Systemfunktionalität und Datenintegrität.
Kurz gesagt, wenn Sie irgendwelche users in Ihrem Workspace haben, die erratbare Bezeichner (E-Mail, user_id) besitzen, sollten Sie die Messenger-Sicherheit aktivieren. Wenn Sie sowohl eingeloggte als auch ausgeloggte users unterstützen, verwenden Sie eine gemischte Strategie für Sicherheit und Benutzerfreundlichkeit. Verwenden Sie JWT-Authentifizierung für eingeloggte Benutzersitzungen, um sensible Informationen zu schützen, während ausgeloggte Besucher eine vereinfachte Messenger-Konfiguration ohne benutzerspezifische Tokens oder Daten nutzen können.
Was sollte ich als Ablaufzeit einstellen?
Sie sollten jedes Mal ein neues JWT senden, wenn der Messenger gestartet wird, sodass die Lebensdauer des Tokens nur die Zeit zwischen den Messenger-Starts abdecken muss. 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. Fügen Sie immer eine Ablaufzeit (exp) in Ihren JWTs hinzu, um die Sicherheit zu erhöhen und die Auswirkungen gestohlener Tokens zu minimieren.
Welchen Signaturalgorithmus kann ich verwenden?
Wir unterstützen:
HS256 (HMAC mit SHA-256). Dieser Algorithmus verwendet einen gemeinsamen geheimen Schlüssel zum Signieren und Verifizieren des Tokens, um sicherzustellen, dass die Daten im Token nicht manipuliert wurden.
RS256 für JWTs, das ein asymmetrisches Schlüsselpaar verwendet – privat zum Signieren und öffentlich zum Verifizieren, als Alternative für erhöhte Sicherheit.
JSON Web Key (JWK)-Konfigurationen, die eine nahtlose Integration mit Fin-generierten Schlüsseln für eine vereinfachte Tokenverwaltung ermöglichen.
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 während der Migration von user_hash zu intercom_user_jwt benötigen.
Wie kann ich überprüfen, ob meine JWTs gültig sind und alles funktioniert?
Siehe Fehlerbehebungsabschnitt oben.
Wie erzwinge ich die Anforderung von JWTs für meinen Workspace?
Sie sollten den Erzwingungs-Schalter 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 > People Data.
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, wird ein neues, kurzlebiges Cookie von 1 Stunde ausgegeben, um negative Auswirkungen auf die Benutzererfahrung zu vermeiden. Um unbeabsichtigte Effekte auf die Benutzererfahrung zu verhindern, empfehlen wir, eine Sitzungsdauer für das Cookie zu wählen, die mit dem Timeout der Anwendungssitzung übereinstimmt.
Warum verlangen wir nicht, dass die gesamte Nutzlast signiert wird?
Wir erlauben Ihnen, 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 Sie diese Möglichkeit nicht benötigen, können Sie alle Ihre User Data Attributes 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 unter Einstellungen > Sicherheit > Messenger rotieren.
Was ist mit der Identitätsüberprüfung passiert? Ersetzen JWTs diese?
Identitätsüberprüfung ist die vorherige Version der Messenger-Sicherheit, die HMAC-User-Hashes verwendet, um zu erkennen, 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 die Identitätsüberprüfung keine zukünftigen Updates erhalten wird.
Wenn Sie Ihre Identitätsüberprüfungs-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 unter Einstellungen > Sicherheit > Messenger tun.
Kann ich Firmendaten in mein JWT aufnehmen, um users mit einer Firma zu verknüpfen?
Ja. Fügen Sie company_id und andere Firmenattribute in Ihre JWT-Nutzlast ein, um users mit einer Firma zu verknüpfen. Dies erstellt und verknüpft die Firma automatisch beim Start, ohne zusätzliche Verzögerung.
Wichtig: Firmendaten, die außerhalb des JWT übermittelt werden (zum Beispiel als company-Objekt in Ihrem Intercom('boot')-Aufruf), werden ignoriert, wenn ein JWT vorhanden ist. Die Firma wird nicht aktualisiert und der last_seen-Wert der Firma wird nicht aktualisiert. Um sicherzustellen, dass Firmendaten korrekt aktualisiert werden, fügen Sie diese in Ihre JWT-Nutzlast ein.