Zum Inhalt

Besucher authentifizieren

Standardmäßig behandelt das Chat-Widget jeden Besucher als anonym und erkennt ihn an seinem Browser. Die Besucher-Authentifizierung ersetzt das durch eine verifizierte Identität: Ihre Website gibt anhand eines von Ihrem Identity Provider signierten Tokens an, wer der Besucher ist, und die Plattform prüft dieses Token, bevor sie irgendetwas darin als vertrauenswürdig ansieht.

Sobald ein Besucher authentifiziert ist, folgt sein Konversationsverlauf der Person statt dem Browser, und Werte aus dem Token — eine Vertragsnummer, ein Kundensegment, ein Name — erreichen den Dialog in einer Form, die der Besucher nicht verändern kann.

Wann Sie sie brauchen

Erwägen Sie die Authentifizierung, wenn einer der folgenden Punkte zutrifft:

  • Der Chat-Verlauf ist aktiviert und Geräte werden gemeinsam genutzt. Ein anonymer Besucher wird an seinem Browser erkannt, nicht an seiner Person — an einem gemeinsam genutzten Rechner kann also der nächste Nutzer desselben Browsers die vorherigen Konversationen öffnen.
  • Der Dialog verarbeitet personenbezogene Daten. Bestellstatus, Rechnungen, Vertragsdaten — alles, was nur die betreffende Person sehen soll.
  • Sie möchten die Konversation mit einem Kundenkonto verknĂĽpfen. Die Authentifizierung ĂĽberträgt Ihre eigene Kundenkennung in die Plattform, sodass Konversationen dem richtigen Datensatz zugeordnet werden können.

Warning

Ohne Authentifizierung ist der Chat-Verlauf an den Browser gebunden. Wer diesen Browser anschlieĂźend verwendet, kann darauf zugreifen. Wo der Dialog personenbezogene Daten verarbeitet, ist genau das das Risiko, dessentwegen es die Authentifizierung gibt.

Funktionsweise

  1. Ihre Website signiert ein Token (JWT), das den Besucher beschreibt. Signiert wird mit dem privaten SchlĂĽssel Ihres Identity Providers.
  2. Die Seite ruft window.daktelaAiChat.authorize() mit diesem Token auf.
  3. Die Plattform prüft die Signatur gegen den von Ihnen konfigurierten öffentlichen Schlüssel und kontrolliert Aussteller, Empfänger und Gültigkeit.
  4. Stimmt alles, stellt die Plattform eine Session aus und die Konversation läuft unter der verifizierten Identität weiter.

Das Widget glaubt der Seite nie einfach, wer der Besucher ist. Alles, dem es vertraut, stammt aus einem Token, das es selbst geprüft hat — deshalb muss der private Schlüssel auf Ihrem Server bleiben und darf niemals in den Browser gelangen.

Der Tab Authentication mit der erwarteten Token-Struktur und dem Hinweis, wie die Anmeldung aufgerufen wird

Ein angemeldeter Besucher sieht im Chat-Header ein Schloss:

Chat-Header mit einem Schloss neben dem Namen des Assistenten

Verifizierung einrichten

Ă–ffnen Sie das Widget, wechseln Sie zum Tab Authentication und aktivieren Sie Enable verification.

Aussteller und Empfänger

Feld Was einzutragen ist
Issuer Muss exakt dem Claim iss im Token entsprechen.
Audience Muss dem Claim aud entsprechen.

Warning

Jedem Chat-Fenster sollte ein eigener Wert unter Audience zugewiesen werden; andernfalls meldet ein fĂĽr ein Fenster ausgestelltes Token den Besucher in jedem anderen Fenster an, das demselben Aussteller vertraut.

SignaturschlĂĽssel

Die Signatur muss asymmetrisch sein — das Token wird mit Ihrem privaten Schlüssel signiert, und die Plattform hält stets nur den zugehörigen öffentlichen Schlüssel. Symmetrische Verfahren wie HS256, bei denen beide Seiten dasselbe Geheimnis teilen, werden nicht akzeptiert. Unterstützt werden RS256/384/512, PS256/384/512 und ES256/384/512; ein bestimmtes Verfahren müssen Sie nicht auswählen.

Wählen Sie unter Public key location, wo die Plattform den öffentlichen Schlüssel suchen soll:

  • JWKS URL — die Adresse Ihres JWKS-Endpunkts. Sie muss HTTPS verwenden und aus dem Internet erreichbar sein. Die SchlĂĽsselrotation erfolgt dann automatisch, was diese Variante ĂĽberall dort zur besseren macht, wo Sie einen solchen Endpunkt anbieten können.
  • Pasted public key — fĂĽr Fälle, in denen kein öffentlicher JWKS-Endpunkt existiert. Tragen Sie Key ID (kid) und Public key (PEM) ein. Die SchlĂĽsselrotation wird damit zu einer manuellen Ă„nderung dieser Konfiguration.

Über Add key lassen sich bis zu fünf öffentliche Schlüssel hinterlegen. Belassen Sie bei einer Rotation den vorherigen Schlüssel in der Liste, bis alle damit signierten Tokens abgelaufen sind.

Identitäts-Claims

Claim carrying the customer ID legt fest, welcher Claim den Besucher identifiziert. Standard ist sub.

Warning

Verwenden Sie einen Claim, den Ihr Identity Provider tatsächlich verifiziert. Der Verweis auf eine unbestätigte E-Mail-Adresse ermöglicht eine Anmeldung unter fremder Identität.

Ăśber Claim carrying the first name (optional) und Claim carrying the surname (optional) lassen sich Vor- und Nachname ĂĽbertragen, damit der Bot den Besucher mit Namen ansprechen kann. FĂĽr mehr werden sie nicht verwendet.

Der Tab Authentication mit ausgefülltem Aussteller, Empfänger, Signaturschlüssel und Identitäts-Claim

Token-Werte in den Dialog ĂĽbernehmen

Unter Carrying token values into the dialog kopiert jede Zeile einen Wert aus dem verifizierten Token in eine Variable, die der Dialog anschlieĂźend liest. Eine Zeile fĂĽgen Sie mit Add mapping hinzu und tragen dann den JWT claim sowie die Context variable ein, in die er ĂĽbernommen wird.

JWT claim Context variable
ps_number $ps_number
segment $segment

Ein Claim, den Sie nicht zuordnen, erreicht den Dialog ĂĽberhaupt nicht.

Ein Claim, der einer Dialog-Kontextvariablen zugeordnet ist, mit dem Diagramm zur Ăśbertragung

Da diese Werte aus einem von der Plattform geprüften Token stammen, kann der Browser sie nachträglich nicht überschreiben — und genau deshalb kann ein Dialog gefahrlos darauf aufbauen.

Was Sie beachten sollten:

  • Gelesen werden nur Claims der obersten Ebene. Ein Punkt gehört zum Namen des Claims und ist kein Pfad in ein verschachteltes Objekt.
  • Ein Claim, den das Token nicht enthält, wird ĂĽbersprungen; der Besucher bleibt angemeldet.
  • FĂĽr Variablennamen wird snake_case empfohlen.
  • Es lassen sich höchstens 10 Claims zuordnen.

Info

Ein Wert mit mehr als 128 Zeichen wird ĂĽbersprungen, und alle ĂĽbertragenen Werte zusammen mĂĽssen in 1 kB passen. Was darĂĽber hinausgeht, erreicht den Dialog nie, und es erfolgt keine Warnung.

Session-Dauer und Token-GĂĽltigkeit

Feld Was es steuert
Session length (seconds) Wie lange eine Anmeldung gültig bleibt, bevor der Chat bei Ihrer Seite ein neues Token anfordert. Die Anmeldung endet immer mit dem, was zuerst eintritt: dieser Dauer oder dem exp im Token. 60–3600 Sekunden, Standard 3600 (eine Stunde).
Longest accepted token lifetime (seconds) Begrenzt, wie lange ein einzelnes Token einen Besucher angemeldet halten kann — unabhängig von der Gültigkeit, mit der es ausgestellt wurde. 60–43200 Sekunden, Standard 43200 (12 Stunden).
Clock drift tolerance (seconds) Die zulässige Abweichung zwischen der Uhr Ihres Signaturservers und der der Plattform. Ein Token, das scheinbar leicht in der Zukunft ausgestellt wurde oder gerade abgelaufen ist, wird innerhalb dieser Toleranz akzeptiert. 0–300 Sekunden, Standard 60.

Tip

Der Identity Provider sollte bei den ausgestellten Tokens eine Gültigkeit (exp) setzen. Ohne sie wird der Autorisierungszeitraum ab dem Ausstellungszeitpunkt gemessen und nur durch Longest accepted token lifetime (seconds) begrenzt — eine deutlich gröbere Schranke.

Die Anmeldung von Ihrer Seite aufrufen

const result = await window.daktelaAiChat.authorize(
  jwt,
  async () => fetchFreshJwt(),   // wird aufgerufen, wenn die Session abläuft
);

if (!result.authorized) {
  console.warn('Chat authorization failed:', result.reason);
}

Drei Dinge entscheiden darĂĽber, ob das in der Praxis gut funktioniert:

  • Der empfohlene Zeitpunkt ist das Laden der Seite, sobald das Token vorliegt — nicht erst das Ă–ffnen des Chats durch den Besucher. Eine Session gehört zu einem Browser-Tab, ein wiederkehrender Besucher hat also keine, bis dieser Aufruf erfolgt. Ein späterer Aufruf wird unterstĂĽtzt und es geht nichts verloren: Das Widget hält bis dahin eine anonyme Session, die die Plattform anschlieĂźend unter der verifizierten Identität zusammenfĂĽhrt. Es kostet allerdings eine zusätzliche Anfragerunde und einen sichtbaren Verbindungsaufbau.
  • Das zweite Argument ist die Funktion, die der Chat nach Ablauf der Session fĂĽr ein neues Token aufruft. Sie muss ein noch gĂĽltiges Token liefern — das darf auch dasselbe wie zuvor sein: Ab läuft die Chat-Session, nicht Ihr Token, ein zwischengespeichertes, noch nicht abgelaufenes Token ist also eine gĂĽltige Antwort. Ein abgelaufenes Token, ein leerer Wert, ein geworfener Fehler oder ein Aufruf, der nie abgeschlossen wird, meldet den Besucher ab, statt es erneut zu versuchen.
  • Der Aufruf gelingt auch dann, wenn die Verifizierung fehlschlägt. Lesen Sie das Ergebnis aus den Feldern authorized und reason und nicht aus einer Ausnahme.

Die vollständige Methodenreferenz finden Sie unter Widget API.

Einstellungen ĂĽberprĂĽfen

Der Tab Authentication enthält den Abschnitt Verify the settings, der einen Besucher direkt in der daneben liegenden Vorschau anmeldet — über dieselbe Schnittstelle window.daktelaAiChat.authorize(), die auch Ihre Seite verwendet.

Wählen Sie entweder Generate a token — der Browser erzeugt ein temporäres Schlüsselpaar, und Add to the configuration übernimmt dessen öffentlichen Schlüssel in die Einstellungen — oder Use an existing token und fügen ein JWT ein, das mit einem bereits konfigurierten Schlüssel signiert wurde. Klicken Sie anschließend auf Sign and verify.

Der PrĂĽfbereich nach einer erfolgreichen Anmeldung in der Vorschau

Info

Geprüft wird die veröffentlichte Konfiguration, nicht laufende Änderungen — bei einem bereits live geschalteten Fenster müssen die Einstellungen daher zuerst gespeichert und veröffentlicht werden. Die Ausnahme ist ein Fenster, das noch nie veröffentlicht wurde: dort wird der Entwurf geprüft, sodass sich die Einstellungen schon vor der ersten Veröffentlichung richtig einstellen lassen. Dabei entstehen eine echte Session und eine echte Konversation; zur Unterscheidung von echten lässt sich der Testmodus der Vorschau aktivieren.

Mit Sign out setzen Sie die Vorschau wieder auf einen anonymen Besucher zurĂĽck.

Abmelden

window.daktelaAiChat.logout() wird aufgerufen, wenn sich der Besucher von Ihrer Website abmeldet. Damit wird die Session serverseitig für alle Tabs und Geräte widerrufen, nicht nur für das aktuelle, und dieser Browser kehrt mit gelöschtem lokalem Verlauf zu einer anonymen Identität zurück.

Zwei Dinge tut die Methode bewusst nicht:

  • Sie beendet die Konversation nicht. Die Unterhaltung bleibt offen und wird im Transkript mit einem Hinweis gekennzeichnet. Der Besucher kann sie nicht anonym fortsetzen, kehrt aber bei erneuter Anmeldung zu ihr zurĂĽck.
  • Sie vergisst den Browser nicht. Der nächste anonyme Besuch wird als derselbe Browser erkannt, der zu diesem Zeitpunkt nichts mehr vom angemeldeten Konto besitzt.

Wie geht es weiter?

Sie brauchen die vollständige Liste der Methoden, die Ihre Seite aufrufen kann — Fenster öffnen, Konversation wechseln, Kontext übergeben, Tools registrieren? Siehe Widget API.