JWT-Authentifizierung

Identifizieren Sie Benutzer in Ihrem Help-Widget, ohne einen separaten Login zu erfordern. Wenn Benutzer in Ihrer App angemeldet sind, können Sie deren Identität über ein von Ihrem Backend signiertes JWT-Token an Ferndesk übergeben.

Sie benötigen Ihr JWT-Geheimnis aus Help Center > Anpassen > Zugriffskontrolle sowie das installierte Ferndesk-SDK.

Wie es funktioniert

Drei-Schritte-Ablauf:

Ihr Frontend erkennt einen angemeldeten Benutzer
Ihr Backend generiert ein signiertes JWT mit Benutzerdetails
Ihr Frontend ruft Ferndesk('identify', { token }) auf

Das Help Center und das Widget wissen nun für Authentifizierung, Personalisierung und Analysen, wer der Benutzer ist.

Die identify-Methode funktioniert nur von der gleichen Domain wie Ihr Help Center oder einer Subdomain der ersten Ebene. Wenn Ihr Help Center unter help.example.com erreichbar ist, können Sie die Identifizierung von app.example.com aus vornehmen, jedoch nicht von otherdomain.com.

JWT serverseitig generieren

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

userId (String): Eindeutige ID in Ihrem System
email (String): E-Mail des Benutzers
name (String, optional): Anzeigename
customAttributes (Objekt, optional): Zusätzliche Metadaten
exp (Zahl, 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({
    userId: 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({
        'userId': 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

Geben Sie Ihr JWT-Geheimnis niemals im clientseitigen Code preis. Speichern Sie es ausschließlich in Umgebungsvariablen auf der Serverseite.

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(token => Ferndesk('identify', { token }))
  .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(token => window.Ferndesk('identify', { token }));
  }
}, [currentUser]);

Rufen Sie identify nach der Initialisierung (init), aber vor dem Öffnen des Widgets auf. Zum Abmelden initialisieren Sie neu, ohne identify aufzurufen.

Überprüfen, ob es funktioniert

Achten Sie auf diese Indikatoren:

Browser-Konsole: Keine Fehler. Ungültige Tokens zeigen Ferndesk: identify failed - invalid token
Kontaktformular: E-Mail und Name werden vorausgefüllt
Analysen: Benutzersitzungen erscheinen in Ihrem Dashboard

Häufige Fehler

identify requires a token

Fehlender Token-Parameter. Prüfen Sie, ob Ihr Backend einen JWT-String zurückgibt.

invalid token

Signaturprüfung fehlgeschlagen. Überprüfen Sie:

Korrektes JWT-Geheimnis
Token ist nicht abgelaufen
Algorithmus ist HS256

must be called from same domain or 1-level subdomain

Domain-Konflikt. Ihre App und Ihr Help Center müssen dieselbe Root-Domain teilen.

Sicherheitshinweise

Token-Ablaufzeit festlegen (1 Stunde ist üblich)
Tokens nur für authentifizierte Benutzer generieren
Überall HTTPS verwenden
Geheimnisse niemals in die Versionskontrolle übertragen

War das hilfreich?