Ferndesk
Authentifizierung

Mit Ihrem Produkt anmelden

Die Anmeldung mit Ihrem Produkt ist ein weiterleitungsbasiertes Single Sign-on: Leser klicken auf der Anmeldeseite Ihres Help Centers auf eine Schaltfläche, melden sich auf der eigenen Anmeldeseite Ihres Produkts an und kehren mit einem kurzlebigen JWT zurück, das ihre Help-Center-Sitzung einrichtet. Die Funktion ist in jedem Tarif verfügbar und funktioniert sowohl mit öffentlichen als auch mit privaten Help Centern.

Was Sie benötigen

  • Eine Anmeldeseite für Ihr Produkt. Sie geben deren URL in Ferndesk ein. Dabei muss es sich um eine vollständige http://- oder https://-URL handeln.

  • Serverseitige JWT-Signierung mit HS256. Ihr Backend signiert das Token, nachdem sich die Leser bei Ihnen angemeldet haben.

  • Eine Eigentümer- oder Administratorrolle in Ihrem Ferndesk-Arbeitsbereich. Nur aktive Arbeitsbereichseigentümer und -administratoren können das Signaturgeheimnis generieren, anzeigen und rotieren.

Anmeldung mit Ihrem Produkt einrichten

Alles wird an einer Stelle konfiguriert: im Dashboard unter Help Center, dann Access Control, auf der Registerkarte Access.

1

Single-Sign-on-Einstellungen öffnen

Gehen Sie im Dashboard zu Help Center, dann zu Access Control, und öffnen Sie die Registerkarte Access. Erweitern Sie Sign in with your product und anschließend Single sign-on.

2

Ihre Login-URL eingeben

Die Login URL ist die Anmeldeseite Ihres Produkts, zu der Leser weitergeleitet werden. Sie muss mit http:// oder https:// beginnen.

Single-Sign-on-Einstellungen mit dem Feld „Login URL“
3

Anmeldeschaltfläche benennen

Der Button name wird den Lesern als Weiter mit <product name> angezeigt. Standardmäßig wird der Name Ihres Help Centers verwendet.

4

Callback-URL kopieren

Im Abschnitt wird eine schreibgeschützte Callback URL angezeigt. Kopieren Sie sie: Ihr Produkt leitet die Leser nach der Anmeldung an diese URL zurück.

5

Signaturgeheimnis generieren

Generieren Sie im Abschnitt Signing secret das Geheimnis, mit dem Ihr Backend JWTs signiert.

6

Optionale Zusatzoptionen festlegen

Unter More options können Sie eine Button logo URL und eine Logout URL hinzufügen. Über die Logout-URL werden Leser weitergeleitet, wenn sie sich über Product SSO vom Help Center abmelden.

Öffnen Sie den Setup guide im Abschnitt, um sofort verwendbare Codebeispiele für Node.js und Python zu erhalten.

Setup guide mit Codebeispielen für die JWT-Signierung

Der Status der Methode zeigt die Konfiguration an: Not set up, solange kein Signaturgeheimnis vorhanden ist, Identify only, wenn ein Geheimnis vorhanden, aber keine gültige Login-URL konfiguriert ist, und Enabled, sobald sowohl das Geheimnis als auch eine gültige Login-URL vorhanden sind.

So funktioniert der Anmeldevorgang

Die Weiterleitung erfolgt über Ihr Produkt, und das signierte Token wird im URL-Fragment an Ferndesk zurückgegeben.

  1. Ein Leser klickt auf die Anmeldeschaltfläche in Ihrem Help Center. Ferndesk sendet ihn mit einem return_to-Abfrageparameter an Ihre Login URL.

  2. Ihr Produkt meldet den Leser an, signiert ein JWT und leitet den Browser mit dem angehängten Token als #jwt=<token> zurück an den Wert von return_to.

  3. Ferndesk validiert das Token und erstellt die Help-Center-Sitzung des Lesers.

Senden Sie das Token im URL-Fragment. Fragmente werden weder an Serverprotokolle noch an den Referer-Header gesendet, sodass das Token dort nicht auftaucht. Der Callback akzeptiert das Token auch als Form-POST oder als ?jwt=-Abfrageparameter.

Über den Weiterleitungs-Callback zurückgegebene Tokens können nur einmal verwendet werden. Jedes Token richtet eine Sitzung ein.

JWT signieren

Mit HS256 signieren. Erforderliche Claims:

Claim

Wert

sub

Stabile, eindeutige Benutzer-ID aus Ihrem System

email

E-Mail-Adresse des Lesers

iat

Zeitstempel der Token-Ausstellung

exp

Zeitstempel des Token-Ablaufs. Das Token darf höchstens 15 Minuten gültig sein.

Optionale Claims:

  • name: Anzeigename des Lesers

  • customAttributes oder metadata: Attribute der Benutzergruppe

Der sub-Claim muss für jeden Benutzer stabil bleiben. Anhand dieses Werts identifiziert Ferndesk den Leser über mehrere Sitzungen hinweg.

Geben Sie das Signaturgeheimnis niemals in clientseitigem Code preis. Speichern Sie es ausschließlich in Umgebungsvariablen des Backends.

Node.js-Beispiel:

const jwt = require('jsonwebtoken');

app.get('/sso/ferndesk', (req, res) => {
  if (!req.user) return res.redirect('/login');

  const returnTo = req.query.return_to;
  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)
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.redirect(returnTo + '#jwt=' + token);
});

Anmeldung testen

Sobald Ihre Anmeldeseite das Token signiert und weiterleitet, klicken Sie im Abschnitt Single sign-on auf Test sign-in, um den Ablauf zu testen, bevor Leser ihn verwenden.

Leser still anmelden (optional)

Für Leser, die bereits bei Ihrem Produkt angemeldet sind, können Sie die Weiterleitung vollständig überspringen. Senden Sie ein mit demselben Signaturgeheimnis signiertes JWT an den Identify-Endpunkt /api/auth/identify oder verwenden Sie den Identify-Ablauf des Widgets. Weitere Informationen zur stillen Identifizierung finden Sie unter JWT-Authentifizierung.

Signaturgeheimnis rotieren

Die Rotation ist auf aktive Arbeitsbereichseigentümer und -administratoren beschränkt – dieselben Rollen, die das Geheimnis generieren und anzeigen können. Durch die Rotation wird das Geheimnis sofort ersetzt, und mit dem alten Geheimnis signierte Tokens funktionieren nicht mehr. Kopieren Sie das neue Geheimnis anstelle des alten in die Umgebungsvariablen Ihres Backends.

Andere Anmeldemöglichkeiten für Leser

War das hilfreich?
War das hilfreich?