JSON-Web-Tokens (JWTs) verhindern, dass Dritte Ihre angemeldeten users imitieren und ihre Gespräche 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 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 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 als echter user gegenüber Ihren Teammitgliedern auszugeben, wodurch er Zugang zu vorherigen Gesprächen und potenziell sensiblen Daten erhält.
Was ist ein JSON-Web-Token (JWT)?
Ein JWT ist ein Industriestandard 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 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 Ihres users entstehen könnten, erheblich verringert wird. Durch die Angabe einer kurzen Ablaufzeit wird das Risiko minimiert.
Sicherere Fin- und AI-Workflows: Übergeben Sie Ihre komplexen Prozesse, Actions und Workflows an Fin, auch wenn sie vertrauenswürdige user-Informationen erfordern.
Durch die sichere Übertragung der user-Identität und -Daten sowie die Durchsetzung der Token-Ablaufzeit stellen JWTs sicher, dass Ihr Fin Messenger im sichersten Zustand ist.
Kundenerlebnis
Bei der Verwendung von JWTs mit dem Fin Messenger gestaltet sich das Erlebnis wie folgt:
Ihre Messenger-Integration startet Ihren angemeldeten user mit einer
Intercom('boot')-Anfrage, die ein JWT enthält, das alle user-Daten 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 Sitzung abläuft und kein neues JWT gesendet wird, endet die Sitzung des users. Der user sieht einen frischen Messenger als abgemeldeten Website-Besucher. Es 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 Gespräche 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.
Tipps:
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 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).
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 intercomUserJwt-Feld in Ihren user-Anfragen 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 user-spezifische Kennungen (wie user_id oder E-Mail) konfigurieren Sie ein abgemeldetes Messenger-Snippet, indem Sie nur die App-ID in Ihrer Einrichtung angeben. Vermeiden Sie das Hinzufügen von user-Attributen, 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 der Messenger API Secret als geheimer Schlüssel dient. Ihren geheimen Schlüssel können Sie in den Sicherheitseinstellungen Ihres Workspaces unter dem Messenger-Tab generieren.
Hinweis: JWT-Tokens müssen für jede user-Sitzung 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 user-Identifikation 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 user-Identifikator. Dies bietet einen konsistenten und sicheren Mechanismus zur user-Identifikation. 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 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 dem Dropdown-Menü "Halten Sie Ihren Messenger sicher" in Ihren Allgemeinen Messenger-Einstellungen 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 für dieses Attribut 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 alle Attribute zu aktivieren, die Sie in Ihrem JWT senden.
Schritt 5: Beenden Sie user-Sitzungen beim Logout
Sie können den Fin Messenger auf jeder öffentlichen Website installieren, 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 angemeldet 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 Gesprächshistorie des zuletzt angemeldeten users sehen, bis der 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 abmelden).
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 den Cookie zu löschen.
Letzter Schritt: Erzwingen Sie die Messenger-Sicherheit für Ihren Arbeitsbereich
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 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 derzeit für Fin Messenger iOS- oder Android-SDKs nicht unterstützt. Für mobile Implementierungen verwenden Sie weiterhin Identity Verification (HMAC-SHA256) anstelle von JWTs, bis SDK-Unterstützung verfügbar ist.
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 unter Einstellungen > Channels > 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 zurück zu Ihrer eigenen App zu verfolgen.
Häufige Fehlermeldungen
HTTP 400 - "user_hash und intercom_user_jwt können nicht gleichzeitig bereitgestellt werden": Die Anfrage enthielt sowohl ein JWT als auch einen user_hash. Kunden sollten entweder einen dieser Werte angeben, aber nicht beide.HTTP 400 - „user_id im Payload fehlt“: Alle JWTs müssen user_id als Teil des Payloads enthalten. Wenn ein Kunde „email“ als primären Bezeichner betrachtet, sollte er den E-Mail-Wert sowohl in user_id als auch in das E-Mail-Feld im Payload einfügen.HTTP 400 - „Ungültiger intercom_user_jwt-Payload“: Der JWT-Payload ist ungültig. Kunden sollten sicherstellen, dass der Payload gut geformt, kodiert und mit einem SHA256 HMAC unter Verwendung des api_secret-Werts als Signaturgeheimnis signiert ist.HTTP 400 - „Intercom_user_jwt abgelaufen“: Das JWT-„exp“ ist ein Zeitstempel in der Vergangenheit. Kunden sollten ein Ablaufdatum in der Zukunft angeben.HTTP 400 - „JWT-Identitätsabweichung": Die im JWT angegebene Benutzer-ID stimmt nicht mit dem Benutzer überein, der mit dem aktiven intercom-Sitzungscookie verknüpft ist. Dies würde darauf hinweisen, 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 - "Ungültiger intercom_user_jwt": Stellen Sie sicher, dass Sie einen gültigen user korrekt booten.Wenn die JWT-Token-Überprüfung fehlschlägt (z. B. aufgrund einer Abweichung in den Ansprüchen oder einer unsachgemäßen Signatur), 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 Decodieren.
Nach dem Decodieren können Sie die Benutzerdetails aus dem Payload Ihres JWT, den Header und eine Notiz sehen, 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 wird.
FAQs
Warum ist user_id im JWT erforderlich?
Sie müssen jetzt user_id als Ihren primären Bezeichner für users angeben. Historisch gesehen haben wir entweder user_id oder email als mögliche Bezeichner unterstützt, aber das hat zu erheblicher Produktverwirrung bei der grundlegenden Identity Verification geführt. Wenn Sie nur eine E-Mail zur Identifizierung Ihrer users haben, können Sie die E-Mail-Adresse sowohl in den user_id- als auch in den email-Attributen des Payloads angeben.
Wie richte ich das für nicht angemeldete 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 booten. Für ausgeloggte Besucher können Sie den Messenger so konfigurieren, dass er ohne Authentifizierung mit einer leichtgewichtigen Version funktioniert. Laden Sie einfach das Messenger-Skript nur mit der App-ID und vermeiden Sie es, Benutzerdaten oder JWT-Tokens zu übergeben. Dies gewährleistet Benutzerfreundlichkeit bei gleichzeitiger Systemfunktionalität und Datenintegrität.
Kurz gesagt, wenn Sie irgendwelche users in Ihrem workspace haben, die erratbare Bezeichner (email, user_id) besitzen, sollten Sie die Messenger-Sicherheit aktivieren. Wenn Sie sowohl angemeldete als auch ausgeloggte users unterstützen, verwenden Sie eine gemischte Strategie für Sicherheit und Benutzerfreundlichkeit. Verwenden Sie JWT-Authentifizierung für angemeldete user-Sitzungen, 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 gewährleisten 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 optimierte 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 tun müssen, wenn sie von user_hash zu intercom_user_jwt migrieren.
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 Erzwingungsschalter 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 Benutzerkonto speichern kann. 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, 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.
Warum verlangen wir nicht, dass der gesamte Payload signiert wird?
Wir ermöglichen es Ihnen, un-signierte Attribute zu senden, um Situationen zu unterstützen, in denen Sie Low-Fidelity-Daten über den User senden müssen, während der User in Ihrer Anwendung aktiv ist. Wenn Sie diese Funktion 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 Workspace > Security > Messenger rotieren.
Was ist mit der Identity Verification passiert? Ersetzen JWTs diese?
Identity Verification ist die vorherige Version der Messenger-Sicherheit, die HMAC-User-Hashes verwendet, 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 unter Settings > Security > Messenger tun.