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 Hilfe-Center > Personalisieren > 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', { 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 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 init, aber vor dem Öffnen des Widgets auf. Um sich abzumelden, initialisieren Sie neu, ohne Identify aufzurufen.

Überprüfen, ob es funktioniert

Prüfen Sie diese Indikatoren:

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

Häufige Fehler

identify requires a token

Fehlender Token-Parameter. Vergewissern Sie sich, dass 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 Hilfe-Center müssen dieselbe Root-Domain nutzen.

Sicherheitshinweise

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

War das hilfreich?