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 ü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.

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', { jwt }) auf

Das Help Center und das Widget wissen nun, wer der Benutzer ist, was Authentifizierung, Personalisierung und Analysen ermöglicht.

Die identify-Methode funktioniert nur von derselben 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 einer anderen Domain wie 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 vom 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]);

Rufen Sie identify nach der Initialisierung (init), aber vor dem Öffnen des Widgets auf. Um sich abzumelden, führen Sie die Initialisierung erneut durch, ohne identify aufzurufen.

Funktionsweise überprüfen

Prü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:

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 das Help Center müssen dieselbe Root-Domain nutzen.

Sicherheitshinweise

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

War das hilfreich?