Benutzerauthentifizierung

Diese Seite beschreibt, wie der Zugriff auf einen eingebetteten Buddy mit Benutzerauthentifizierung abgesichert wird – von der Generierung des Key Pairs im Buddy Management über die Token-Erzeugung im eigenen System (z. B. TYPO3) bis zur Einbettung des Buddys mit Token-Übergabe.

Damit lässt sich der Buddy in eine eigene Anwendung einbinden, aber nur für berechtigte Benutzer oder Benutzergruppen verfügbar machen. Sollen mehrere Benutzergruppen getrennt werden (z. B. eine TYPO3-Benutzergruppe pro Bundesland), wird pro Gruppe ein eigener Buddy mit eigenem Key Pair verwendet.

Die Authentifizierung basiert auf einem asymmetrischen Schlüsselpaar (Public/Private Key):

1. Die eigene Anwendung (z. B. TYPO3) authentifiziert den Benutzer wie gewohnt selbst.
2. Für berechtigte Benutzer erzeugt die Anwendung einen JWT-Token und signiert ihn mit dem Private Key.
3. Die Webseite übergibt den Token per postMessage an den eingebetteten Buddy (Iframe).
4. Der Buddy sendet den Token bei jeder Anfrage mit und verifiziert ihn serverseitig mit dem im Buddy hinterlegten Public Key.
5. Anfragen ohne gültigen Token werden abgelehnt (403 Forbidden).

Der Private Key verbleibt ausschließlich im eigenen System und wird niemals an Buddy übertragen. Im Buddy wird nur der Public Key hinterlegt.

Die Konfiguration erfolgt in den Einstellungen des jeweiligen Buddys unter Assistent > Sonstiges > Zugriff einschränken > Benutzerauthentifizierung.

• Im Buddy Management beim gewünschten Assistenten das Menü öffnen und Bearbeiten wählen.

• Im Tab Assistent den Abschnitt Sonstiges aufklappen.
• Zugriff einschränken aktivieren.
• Benutzerauthentifizierung aktivieren – dadurch erscheint das Feld Public Key.

• Auf Neues Key Pair generieren klicken und den Dialog bestätigen.

• Der Public Key wird automatisch in das Feld eingetragen. Der Private Key wird in einem Dialog einmalig angezeigt und kann dort kopiert werden.

• Die Konfiguration speichern.

Wichtig: Der Private Key wird nur einmalig angezeigt und nicht im Buddy Management gespeichert. Er muss sofort kopiert und an einem sicheren Ort (z. B. Passwort-/Secret-Manager) abgelegt werden. Geht er verloren, muss ein neues Key Pair generiert werden.

Hinweise:

• Das Key Pair wird direkt im Browser erzeugt: RSA 2048 Bit, Signaturverfahren RS256. Der Public Key liegt im PEM-Format (-----BEGIN PUBLIC KEY-----) vor, der Private Key im PKCS#8-PEM-Format (-----BEGIN PRIVATE KEY-----).
• Alternativ kann auch ein extern erzeugter Public Key (PEM) direkt in das Feld eingefügt werden, wenn das Key Pair im eigenen System generiert werden soll.
• Pro Buddy wird genau ein Public Key hinterlegt. Für mehrere Benutzergruppen (z. B. je Bundesland) wird daher pro Gruppe ein eigener Buddy mit eigenem Key Pair angelegt.

Die eigene Anwendung stellt für jeden berechtigten Benutzer einen JWT aus, signiert mit dem Private Key und dem Algorithmus RS256.

Erwartete Claims:

• sub: Eindeutige Benutzer-ID im eigenen System. Wird von Buddy als Chat-Benutzer-ID verwendet (z. B. für die Chat-Historie).
• exp: Ablaufzeitpunkt des Tokens. Eine kurze Lebensdauer wird empfohlen (z. B. 30 Minuten, siehe Token-Erneuerung).

Beispiel-Payload:

{
  "sub": "typo3-user-4711",
  "exp": 1767225600
}

Für die Token-Erstellung kann jede gängige JWT-Bibliothek verwendet werden (z. B. firebase/php-jwt für PHP/TYPO3, jsonwebtoken für Node.js, PyJWT für Python).

Wichtig: Der Token darf nur serverseitig erzeugt werden. Der Private Key darf niemals im Frontend/Browser der eigenen Anwendung landen.

Der sub-Claim wird von Buddy als eindeutige Benutzer-ID verwendet. Wenn Buddy die ursprüngliche Benutzer-ID des externen Systems nicht kennen soll, sollte stattdessen eine pseudonymisierte ID übertragen werden.

Empfohlen wird eine stabile Ableitung mit HMAC-SHA256:

HMAC-SHA256(geheimer_schlüssel, ursprüngliche_benutzer_id)

Beispiel:

{ "sub": "84b41f95d03a1d690614de9063fddf097d6d03d688db77b4c79e13a2d6930b8e", "exp": 1767225600 }

Die erzeugte ID muss für denselben Benutzer dauerhaft gleich und für unterschiedliche Benutzer eindeutig sein. Der verwendete HMAC-Schlüssel bleibt ausschließlich im Backend und wird wie ein Secret behandelt.

Ein einfacher Hash ohne geheimen Schlüssel, beispielsweise SHA256(benutzer_id), wird nicht empfohlen, da vorhersehbare Benutzer-IDs durch Ausprobieren erkannt werden könnten.

Die fertigen Einbettungs-Snippets stehen im Buddy Management über das Menü des Assistenten unter Teilen bereit, im Tab Einbettung mit Benutzerauthentifizierung.

Die fertigen Einbettungs-Snippets stehen im Buddy Management über das Menü des Assistenten unter Teilen bereit, im Tab Einbettung mit Benutzerauthentifizierung.

Der Ablauf:

1. Die Iframe-URL muss den Parameter auth_strategy=user_token enthalten. Damit wartet der Buddy auf den Token, bevor er startet.
2. Sobald der Chat bereit ist, sendet er eine chat_loaded-Nachricht an die einbettende Seite.
3. Die Seite antwortet per postMessage mit type: "set_user_token" und übergibt den JWT.

Wichtig: Ohne auth_strategy=user_token in der Iframe-URL könnte der Buddy einen zwischengespeicherten Session-Token verwenden, bevor der eigene Token eintrifft.

Aus Sicherheitsgründen haben JWT-Tokens eine begrenzte Lebensdauer. Damit der Benutzer den Chat nicht neu laden muss, sollte der Token regelmäßig erneuert und erneut per postMessage übergeben werden – üblicherweise in einem Intervall von etwa der halben Token-Lebensdauer (z. B. alle 15 Minuten bei 30 Minuten Gültigkeit).

Ein vollständiges Beispiel-Skript für die Token-Erneuerung befindet sich ebenfalls im Dialog Teilen unter Skript für Token-Erneuerung.

• Erhält der eingebettete Buddy innerhalb von ca. 15 Sekunden keinen Token, schlägt das Laden des Chats fehl.
• Anfragen mit fehlendem, abgelaufenem oder falsch signiertem Token werden mit 403 Forbidden – "User token is invalid or missing." abgelehnt.
• Typische Fehlerursachen:
  • Token mit einem anderen Key Pair signiert als im Buddy hinterlegt
  • abgelaufener Token (exp) ohne funktionierende Token-Erneuerung
  • fehlender Parameter auth_strategy=user_token in der Iframe-URL
  • falscher Algorithmus (es wird ausschließlich RS256 akzeptiert)

• Die Einrichtung der Benutzerauthentifizierung besteht im Wesentlichen aus folgenden Schritten:

  1. Im Buddy unter Assistent > Sonstiges Zugriff einschränken und Benutzerauthentifizierung aktivieren
  2. Key Pair generieren, Private Key einmalig kopieren und sicher ablegen
  3. Im eigenen System (z. B. TYPO3) JWT mit RS256 und Private Key signieren (sub = Benutzer-ID, kurze exp)
  4. Buddy mit auth_strategy=user_token einbetten und Token per postMessage (set_user_token) übergeben
  5. Token-Erneuerung implementieren, damit die Sitzung nicht abbricht

  Zusätzlich gilt:

  • Der Private Key wird nur einmal angezeigt und niemals an Buddy übertragen
  • Pro Benutzergruppe (z. B. je Bundesland) ein eigener Buddy mit eigenem Key Pair
  • Die fertigen Einbettungs-Snippets stehen im Dialog Teilen des Assistenten bereit