JWT-Authentifizierung

Identifizieren Sie Benutzer in Ihrem Hilfe-Widget, ohne eine separate Anmeldung zu erfordern. Wenn Benutzer in Ihrer App angemeldet sind, können Sie ihre Identität mithilfe eines von Ihrem Backend signierten JWT-Tokens an Ferndesk übergeben.

So funktioniert es

Ablauf in drei Schritten:

1. Ihr Frontend erkennt einen angemeldeten Benutzer

2. Ihr Backend generiert ein signiertes JWT mit den Benutzerdaten

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

Das Help Center und das Widget wissen nun, wer der Benutzer ist, und können Authentifizierung, Personalisierung und Analysen ermöglichen.

JWT-Secret

Bevor Sie JWTs signieren können, benötigen Sie ein Signier-Secret aus Ihrem Ferndesk-Dashboard:

1. Gehen Sie zu Help Center > Access Control.

2. Erweitern Sie im Abschnitt Benutzeridentifikation den Eintrag JWT identify.

3. Klicken Sie auf Secret generieren.

Durch das Generieren eines Secrets wird die JWT-Authentifizierung für Ihr Help Center automatisch aktiviert. Das Secret wird nach der Generierung maskiert. Kopieren Sie es sofort und speichern Sie es sicher in den Umgebungsvariablen Ihres Backends. Sie können es später im Dashboard wieder anzeigen.

Wenn Sie das Secret ändern müssen, klicken Sie auf Neu generieren. Dadurch wird das vorhandene Secret ersetzt und alle mit dem alten Secret signierten Tokens werden ungültig. Aktualisieren Sie Ihr Backend mit dem neuen Secret, bevor Benutzer betroffen sind.

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

JWT identify funktioniert in Ihrem Produkt unbemerkt. KI-Clients melden Benutzer stattdessen über einen Browser an.

Unter JWT identify im Bereich Browser-Anmeldung (MCP- und KI-Clients):

1. Geben Sie Ihre URL der SSO-Anmeldeseite ein. Ferndesk leitet Benutzer mit einem return_to-Parameter hierher weiter. Leiten Sie sie nach der Anmeldung mit einem jwt-Abfrageparameter zu return_to weiter.

2. Aktivieren Sie optional E-Mail-Anmeldung für KI-Clients erlauben, damit bestehende Benutzer beim Verbinden eines KI-Clients ihre E-Mail-Inhaberschaft bestätigen können. Lassen Sie diese Option deaktiviert, wenn Benutzerattribute den Zugriff auf vertrauliche Inhalte steuern.

3. Klicken Sie auf Änderungen speichern.

Verwenden Sie eine gültige http:- oder https:-URL. Ungültige Werte zeigen Geben Sie eine gültige URL der Anmeldeseite einschließlich https:// ein an.

Verwandt: Ferndesk mit KI-Tools verwenden · Lesern die Nutzung Ihres Help Centers in KI-Tools ermöglichen

JWT serverseitig generieren

Erstellen Sie einen Endpunkt, der ein signiertes Token zurückgibt. Ferndesk erfordert keine iss- (Issuer) oder aud- (Audience) Claims.

Erforderliche Claims:

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

• email (String, erforderlich): E-Mail-Adresse des Benutzers

• exp (Zahl, erforderlich): Zeitstempel des Ablaufs des Tokens

• iat (Zahl, erforderlich): Zeitstempel der Token-Ausstellung

Optionale Claims:

• name (String, optional): Anzeigename

• customAttributes (Objekt, optional): Zusätzliche Benutzerattribute. Sie können 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 + 900, // 15 minutes (maximum token age)
    customAttributes: { plan: req.user.plan }
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Python-Beispiel:

import jwt
import os\nimport 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 + 900,  # 15 minutes (maximum token age)
        'customAttributes': {'plan': current_user.plan}
    }, os.environ['FERNDESK_JWT_SECRET'], algorithm='HS256')

    return token

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]);

Funktion überprüfen

Prüfen Sie diese Hinweise:

• Browserkonsole: Keine Fehler. Ungültige JWTs zeigen Ferndesk: identify failed (Invalid or expired token). an.

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

• Analysen: Benutzersitzungen werden in Ihrem Dashboard angezeigt.

Häufige Fehler

Ferndesk: identify requires a jwt

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

invalid jwt

Die Signaturüberprüfung oder die Validierung der Claims ist fehlgeschlagen. Überprüfen Sie:

• Das korrekte JWT-Secret stimmt mit dem in Ferndesk gespeicherten Secret überein

• Das Token ist nicht abgelaufen

• Der Algorithmus ist HS256

• Die erforderlichen 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 Benutzers bereits in Ihrem Help Center vorhanden ist, jedoch mit einer anderen Subject-ID. Das bedeutet, dass sich zuvor jemand mit dieser E-Mail-Adresse über ein anderes Identitätssystem oder einen anderen sub-Wert angemeldet hat.

So beheben Sie das Problem:

• Stellen Sie sicher, dass Ihr Backend für jeden Benutzer immer denselben sub sendet.

• Wenn Sie das System für Benutzer-IDs geändert haben, muss der betroffene Benutzer in Ferndesk erneut bereitgestellt werden.

must be called from same domain or 1-level subdomain

Die Quelle stimmt nicht überein. Nachfolgende Widget-Sitzungsanfragen müssen von exakt der Quelle stammen, über die die Identifizierung durchgeführt wurde, einschließlich Schema, Host und Port.

Sicherheitshinweise

• Legen Sie den Token-Ablauf auf 15 Minuten oder weniger fest

• Generieren Sie Tokens nur für authentifizierte Benutzer

• Verwenden Sie überall HTTPS

• Übernehmen Sie Secrets niemals in die Versionsverwaltung

• Halten Sie Ihre sub-Werte stabil. Ferndesk speichert die Identität anhand des Subjects dauerhaft.