JWT-Authentifizierung

Identifizieren Sie Benutzer in Ihrem Hilfe-Widget, ohne dass eine separate Anmeldung erforderlich ist. Wenn Benutzer in Ihrer App angemeldet sind, können Sie deren Identität mit einem von Ihrem Backend signierten JWT-Token an Ferndesk übermitteln.

So funktioniert es

Ablauf in drei Schritten:

1. Ihr Frontend erkennt einen angemeldeten Benutzer

2. Ihr Backend generiert ein signiertes JWT mit Benutzerdetails

3. Ihr Frontend ruft Ferndesk('identify', { jwt }) auf

Das Hilfe-Center und das Widget kennen nun die Identität des Benutzers für Authentifizierung, Personalisierung und Analysen.

JWT-Geheimnis

Bevor Sie JWTs signieren können, benötigen Sie ein Signatur-Geheimnis aus Ihrem Ferndesk-Dashboard:

1. Gehen Sie zu Help Center und klicken Sie unter Verwalten auf Access Control.

2. Erweitern Sie die Zeile JWT identification

3. Klicken Sie auf Generate Secret

Das Geheimnis wird nur einmal angezeigt, wenn Sie es generieren. Kopieren Sie es sofort und speichern Sie es sicher in Ihren Backend-Umgebungsvariablen. Sie können es später nicht mehr einsehen.

Wenn Sie Ihr Geheimnis verlieren, müssen Sie es löschen und ein neues generieren. Dadurch werden alle vorhandenen JWT-Token, die mit dem alten Geheimnis signiert wurden, ungültig, bis Sie Ihr Backend auf das neue aktualisieren.

JWT serverseitig generieren

Erstellen Sie einen Endpunkt, der ein signiertes Token zurückgibt. Erforderliche Claims:

• sub (string, erforderlich): Eindeutige ID in Ihrem System, die diesen Benutzer identifiziert. Dies ist der primäre Identitätsschlüssel.

• email (string, erforderlich): E-Mail-Adresse des Benutzers

• name (string, optional): Anzeigename

• customAttributes (object, optional): Zusätzliche Metadaten

• exp (number, empfohlen): Zeitstempel für den Ablauf des Tokens

Node.js-Beispiel:

const jwt = require('jsonwebtoken');

app.get('/api/ferndesk-token', async (req, res) => {if (!req.user) return res.status(401).json({ error: 'Not authenticated' });

  const token = jwt.sign({
    sub: req.user.id,
    email: req.user.email,
    name: req.user.name,
    exp: Math.floor(Date.now() / 1000) + 3600 // 1 hour
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Python-Beispiel:

import jwt
import time

@app.route('/api/ferndesk-token')
def ferndesk_token():
    if not current_user:
        return {'error': 'Not authenticated'}, 401

    token = jwt.encode({
        'sub': current_user.id,
        'email': current_user.email,
        'name': current_user.name,
        'exp': int(time.time()) + 3600
    }, os.environ['FERNDESK_JWT_SECRET'], algorithm='HS256')

    return token

Identify von Ihrem Frontend aus aufrufen

Rufen Sie das Token von Ihrem Backend ab und übergeben Sie es an das SDK:

Ferndesk('init', { widgetId: 'your-widget-id' });

fetch('/api/ferndesk-token').then(r => r.text())
  .then(jwt => Ferndesk('identify', { jwt }))
  .catch(err => console.error('Identification failed:', err));

React-Beispiel:

useEffect(() => {
  window.Ferndesk('init', { widgetId: 'your-widget-id' });

  if (currentUser) {
    fetch('/api/ferndesk-token')
      .then(r => r.text())
      .then(jwt => window.Ferndesk('identify', { jwt }));
  }
}, [currentUser]);

Funktion überprüfen

Überprüfen Sie diese Indikatoren:

• Browser-Konsole: Keine Fehler. Ungültige JWTs zeigen Ferndesk: identify failed - invalid jwt an

• Kontaktformular: E-Mail und Name werden vorausgefüllt

• Analysen: Benutzersitzungen erscheinen in Ihrem Dashboard

Häufige Fehler

Ferndesk: identify requires a jwt

Fehlender jwt-Parameter. Überprüfen Sie, ob Ihr Backend einen JWT-String zurückgibt.

invalid jwt

Signaturprüfung fehlgeschlagen. Überprüfen Sie:

• Das korrekte JWT-Geheimnis stimmt mit dem in Ferndesk gespeicherten Wert überein

• Das Token ist nicht abgelaufen

• Der Algorithmus ist HS256

JWT subject does not match the existing help-center user

Dieser Fehler tritt auf, wenn die E-Mail eines Benutzers bereits in Ihrem Hilfe-Center existiert, aber mit einer anderen Subject-ID verknüpft ist. Das bedeutet, dass sich jemand zuvor mit dieser E-Mail über ein anderes Identitätssystem oder einen anderen sub-Wert angemeldet hat.

Zur Lösung:

• Stellen Sie sicher, dass Ihr Backend für jeden Benutzer immer denselben sub sendet

• Wenn Sie die Benutzer-ID-Systeme gewechselt haben, muss der betroffene Benutzer in Ferndesk neu bereitgestellt werden

must be called from same domain or 1-level subdomain

Domain-Fehlabgleich. Ihre App und das Hilfe-Center müssen eine Root-Domain teilen.

Sicherheitshinweise

• Ablaufzeit des Tokens festlegen (1 Stunde ist üblich)

• Token nur für authentifizierte Benutzer generieren

• Überall HTTPS verwenden

• Geheimnisse niemals in die Versionskontrolle übertragen

• Halten Sie Ihre sub-Werte stabil – Ferndesk speichert Identitäten basierend auf dem Betreff