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 mithilfe eines von Ihrem Backend signierten JWT-Tokens 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 Hilfe-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 Hilfe-Center oder einer Subdomain der ersten Ebene. Wenn sich Ihr Hilfe-Center unter help.example.com befindet, können Sie die Identifizierung von app.example.com aus vornehmen, aber nicht von otherdomain.com.

Das 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(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, aber vor dem Öffnen des Widgets auf. Zum Abmelden initialisieren Sie neu, 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

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

invalid jwt

Signaturüberprü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-Abweichung. Ihre App und das Hilfe-Center müssen dieselbe Root-Domain teilen.

Sicherheitshinweise

Token-Ablauf festlegen (1 Stunde ist üblich)
Token nur für authentifizierte Benutzer generieren
Überall HTTPS verwenden
Geheimnisse niemals in der Versionskontrolle einchecken

War das hilfreich?