JWT-Authentifizierung

Identifizieren Sie Benutzer in Ihrem Hilfe-Widget, ohne eine separate Anmeldung zu benötigen. 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 ihn authentifizieren sowie Personalisierung und Analysen ermöglichen.

JWT-Secret

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

1. Gehen Sie zu Help Center > Access Control.

2. Öffnen Sie den Tab Access.

3. Suchen Sie im Abschnitt Sign in with your product unter Single sign-on den Bereich Signing secret.

4. Klicken Sie auf Generate Secret.

Der Abschnitt zeigt einen Status an: Not set up bedeutet, dass noch kein Secret existiert. Identify only bedeutet, dass das Secret für die stille Identifizierung funktioniert, Leser sich aber noch nicht über Ihr Produkt anmelden können, weil keine gültige Login-URL konfiguriert ist. Enabled bedeutet, dass sowohl das Secret als auch eine gültige Login-URL vorhanden sind.

Das Secret wird nach der Generierung verborgen. Kopieren Sie es sofort und speichern Sie es sicher in den Umgebungsvariablen Ihres Backends. Sie können es später im Dashboard erneut anzeigen.

Eine stille Identifizierung ist auch möglich, indem Sie ein mit demselben Secret signiertes JWT an den Identify-Endpunkt /api/auth/identify senden.

Nur aktive Workspace-Inhaber und Administratoren können das Secret generieren, anzeigen, rotieren oder löschen. Andere Workspace-Mitglieder sehen anstelle der Secret-Verwaltungsoptionen einen Hinweis, einen Inhaber oder Administrator zu fragen.

Wenn Sie das Secret rotieren müssen, klicken Sie auf Regenerate und bestätigen Sie die Rotation im Dialog Regenerate the JWT signing secret?. Das vorhandene Secret wird ersetzt, und alle mit dem alten Secret signierten Tokens funktionieren sofort nicht mehr. Stellen Sie das neue Secret in Ihrem Backend bereit, bevor die Anmeldung im Help Center wieder funktioniert.

Mit Ihrem Produkt anmelden

Leser melden sich über die eigene Anmeldeseite des Help Centers mit den vom Help Center aktivierten Methoden an. Eine dieser Methoden ist die Anmeldung über Ihr Produkt: Das Help Center leitet den Leser zu Ihrem Produkt weiter, Ihr Backend signiert ein kurzlebiges JWT, und der Leser kehrt beim Help Center angemeldet zurück. Dasselbe Signatur-Secret unterstützt auch die stille Identifizierung innerhalb Ihrer App.

KI-Clients, die Ihr Help Center über MCP lesen, melden sich im Browser mit den eigenen Anmeldemethoden des Help Centers an.

Die Einrichtungsschritte finden Sie unter Mit Ihrem Produkt anmelden.

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 Token-Ablaufs

• 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 im Frontend 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]);

Überprüfen, ob es funktioniert

Prüfen Sie diese Hinweise:

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

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

• Analysen: Benutzersitzungen erscheinen in Ihrem Dashboard.

Häufige Fehler

Ferndesk: identify requires a jwt

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

invalid jwt

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

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

• Das Token ist noch nicht abgelaufen.

• Der Algorithmus ist HS256, HS384 oder HS512 (die obigen Beispiele verwenden 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 jemand zuvor 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-Wert sendet.

• Wenn Sie das Benutzer-ID-System geändert haben, muss der betroffene Benutzer in Ferndesk neu bereitgestellt werden.

must be called from same domain or 1-level subdomain

Ursprungsabweichung. Nachfolgende Widget-Sitzungsanfragen müssen vom exakt gleichen Ursprung stammen, von dem 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.

• Committen Sie Secrets niemals in die Versionsverwaltung.

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