JWT-Authentifizierung

Identifizieren Sie Benutzer in Ihrem Hilfe-Widget, ohne dass ein separater Login erforderlich ist. 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 unter Help Center > Customize > Access Control sowie das installierte Ferndesk SDK.

So funktioniert es

Ablauf in drei Schritten:

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

Das Hilfe-Center und das Widget wissen nun, wer der Benutzer ist, um Authentifizierung, Personalisierung und Analysen zu ermöglichen.

Die identify-Methode funktioniert nur von derselben Domain wie Ihr Hilfe-Center oder einer Subdomain der ersten Ebene. Wenn Ihr Hilfe-Center unter help.example.com liegt, 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-Adresse 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. Um sich abzumelden, initialisieren Sie neu, ohne identify aufzurufen.

Funktionsweise überprüfen

Achten Sie auf diese Indikatoren:

Browser-Konsole: Keine Fehler. Ungültige Token zeigen Ferndesk: identify failed - invalid token an
Kontaktformular: E-Mail und Name werden vorausgefüllt
Analytics: 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-Fehlermeldung. Ihre App und das Hilfe-Center müssen dieselbe Root-Domain verwenden.

Sicherheitshinweise

Legen Sie einen Token-Ablauf fest (1 Stunde ist üblich)
Generieren Sie Token nur für authentifizierte Benutzer
Verwenden Sie überall HTTPS
Übertragen Sie Geheimnisse niemals in die Versionsverwaltung

War das hilfreich?