JWT-Authentifizierung

Identifiziere Nutzer in deinem Hilfe-Widget, ohne dass eine separate Anmeldung erforderlich ist. Wenn Nutzer in deiner App angemeldet sind, kannst du ihre Identität über einen mit deinem Backend signierten JWT-Token an Ferndesk übergeben.

So funktioniert es

Dreistufiger Ablauf:

1. Dein Frontend erkennt einen angemeldeten Nutzer

2. Dein Backend generiert einen signierten JWT mit Nutzerdetails

3. Dein Frontend ruft Ferndesk('identify', { jwt }) auf

Das Help Center und das Widget wissen jetzt, wer der Nutzer ist – für Authentifizierung, Personalisierung und Analysen.

JWT-Geheimnis

Bevor du JWTs signieren kannst, brauchst du ein Signiergeheimnis aus deinem Ferndesk-Dashboard:

1. Gehe zu Help Center > Access Control.

2. Erweitere im Abschnitt User identification die Zeile JWT identify.

3. Klicke auf Generate Secret.

Das Generieren eines Geheimnisses aktiviert automatisch die JWT-Authentifizierung für dein Help Center. Das Geheimnis wird nur einmal angezeigt. Kopiere es sofort und bewahre es sicher in den Umgebungsvariablen deines Backends auf. Du wirst es später nicht mehr ansehen können.

Wenn du das Geheimnis rotieren musst, klicke auf Regenerate. Dadurch wird das vorhandene Geheimnis ersetzt und alle mit dem alten Geheimnis signierten Tokens werden ungültig. Aktualisiere dein Backend mit dem neuen Geheimnis, bevor sich dies auf Nutzer auswirkt.

Browser-Anmeldung für MCP- und KI-Clients

JWT identify läuft in deinem Produkt im Hintergrund. KI-Clients melden Nutzer stattdessen über einen Browser an.

In JWT identify unter Browser sign-in (MCP and AI clients):

1. Gib deine SSO login page URL ein. Ferndesk leitet Nutzer mit einem return_to-Parameter dorthin weiter. Nach der Anmeldung leite zu return_to mit einem jwt-Abfrageparameter weiter.

2. Aktiviere optional Allow email sign-in for AI clients, damit bestehende Nutzer beim Verbinden eines KI-Clients den Besitz ihrer E-Mail-Adresse nachweisen können. Lasse dies deaktiviert, wenn Benutzerattribute sensible Inhalte steuern.

3. Klicke auf Save changes.

Verwende eine gültige http:- oder https:-URL. Ungültige Werte zeigen Enter a valid login page URL, including https:// an.

Verwandt: Ferndesk mit KI-Tools verwenden · Lesern erlauben, dein Help Center in KI-Tools zu verwenden

JWT serverseitig generieren

Erstelle einen Endpunkt, der einen signierten Token zurückgibt. Ferndesk benötigt keine iss- (Issuer) oder aud- (Audience) Claims.

Erforderliche Claims:

• sub (string, erforderlich): Eindeutige ID in deinem System, die diesen Nutzer identifiziert. Dies ist der primäre Identitätsschlüssel.

• email (string, erforderlich): E-Mail-Adresse des Nutzers

• exp (number, erforderlich): Ablaufzeitstempel des Tokens

• iat (number, erforderlich): Ausstellungszeitstempel des Tokens

Optionale Claims:

• name (string, optional): Anzeigename

• customAttributes (object, optional): Zusätzliche Nutzerattribute. Du kannst auch metadata verwenden; beide Schlüssel werden akzeptiert.

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 now = Math.floor(Date.now() / 1000);
  const token = jwt.sign({
    sub: req.user.id,
    email: req.user.email,
    name: req.user.name,
    iat: now,
    exp: now + 3600, // 1 hour
    customAttributes: { plan: req.user.plan }
  }, 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

    now = int(time.time())
    token = jwt.encode({
        'sub': current_user.id,
        'email': current_user.email,
        'name': current_user.name,
        'iat': now,
        'exp': now + 3600,
        'customAttributes': {'plan': current_user.plan}
    }, os.environ['FERNDESK_JWT_SECRET'], algorithm='HS256')

    return token

Identify in deinem Frontend aufrufen

Rufe den Token aus deinem Backend ab und übergib ihn an die 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]);

Prüfen, ob alles funktioniert

Achte auf diese Anzeichen:

• Browserkonsole: Keine Fehler. Ungültige JWTs zeigen Ferndesk: identify failed - invalid jwt

• Kontaktformular: E-Mail und Name werden vorausgefüllt

• Analytics: Nutzersitzungen erscheinen in deinem Dashboard

Häufige Fehler

Ferndesk: identify requires a jwt

Fehlender jwt-Parameter. Prüfe, ob dein Backend einen JWT-String zurückgibt.

invalid jwt

Die Signaturprüfung oder die Validierung der Claims ist fehlgeschlagen. Prüfe:

• Das richtige JWT-Geheimnis stimmt mit dem in Ferndesk gespeicherten überein

• Der Token ist nicht abgelaufen

• Der Algorithmus ist HS256

• Erforderliche Claims sind vorhanden: sub, email, exp und iat

JWT subject does not match the existing help-center user

Dieser Fehler tritt auf, wenn die E-Mail-Adresse eines Nutzers in deinem Help Center bereits vorhanden ist, aber mit einer anderen Subject-ID. Das bedeutet, dass sich jemand zuvor mit dieser E-Mail-Adresse über ein anderes Identitätssystem oder einen anderen sub-Wert angemeldet hat.

Zur Behebung:

• Stelle sicher, dass dein Backend für jeden Nutzer immer denselben sub sendet

• Wenn du das Nutzers-ID-System geändert hast, muss der betroffene Nutzer in Ferndesk erneut bereitgestellt werden

must be called from same domain or 1-level subdomain

Domain-Mismatch. Deine App und dein Help Center müssen dieselbe Root-Domain teilen.

Sicherheitshinweise

• Token-Ablauf festlegen (1 Stunde ist üblich)

• Tokens nur für authentifizierte Nutzer generieren

• Überall HTTPS verwenden

• Geheimnisse niemals in die Versionsverwaltung einchecken

• Halte deine sub-Werte stabil. Ferndesk speichert die Identität anhand des Subjects.