Das Weiterleitungs-Token wurde zweimal gesendet, häufig durch eine Seite, die neu geladen wird. Signieren Sie für jede Weiterleitung ein neues Token.
Leser mit JWT oder OIDC anmelden
Leser können sich mit einem Konto, das sie bereits besitzen, in Ihrem Help Center anmelden. Ein privates Help Center lässt sie anschließend hinein, und Gruppenregeln legen fest, was sie sehen. Dafür gibt es zwei Möglichkeiten: ein JWT aus Ihrer eigenen App oder OIDC von einem Identitätsanbieter wie Okta, Auth0 oder Azure AD. Was das für Ihr Team bedeutet, erfahren Sie unter Ihr Help Center privat machen.
Inhaber und Administratoren richten beides unter Help Center > Zugriffskontrolle ein. Die JWT-Anmeldung ist in allen Tarifen verfügbar. OIDC, private Help Center und Gruppenregeln hängen von Ihrem Tarif ab. Weitere Informationen finden Sie unter Preise und Tarife.
JWT: Anmeldung mit Ihrem Produkt
Ein Leser wählt auf der Anmeldeseite des Help Centers Weiter mit Ihrem Produkt aus. Wenn JWT die einzige Anmeldemethode ist, überspringt das Help Center diese Seite und fährt direkt fort.
Das Help Center leitet den Leser mit einem
return_to-Parameter zu Ihrer Anmelde-URL weiter. Eine bereits in Ihrer Anmelde-URL vorhandene Abfragezeichenfolge bleibt erhalten.Ihre App meldet den Leser bei Bedarf an, signiert ein JWT mit dem Signaturschlüssel des Help Centers und leitet mit dem Token im Fragment zu
return_toweiter:#jwt=TOKEN.Das Help Center überprüft das Token, startet eine 180 Tage gültige Sitzung und leitet den Leser zurück zur gewünschten Seite.
import { SignJWT } from 'jose';
const secret = new TextEncoder().encode(process.env.FERNDESK_SIGNING_SECRET);
// Your login URL: the reader is signed in to your app here
app.get('/help-center/sso', requireLogin, async (req, res) => {
const now = Math.floor(Date.now() / 1000);
const token = await new SignJWT({
email: req.user.email,
name: req.user.name,
metadata: { plan: req.user.plan, roles: req.user.roles }
})
.setProtectedHeader({ alg: 'HS256' })
.setSubject(String(req.user.id))
.setIssuedAt(now)
.setExpirationTime(now + 300)
.sign(secret);
res.redirect(req.query.return_to + '#jwt=' + token);
});Der Callback akzeptiert das Token auch als POST-Formularfeld oder als ?jwt=-Abfrageparameter; token funktioniert ebenfalls als Feldname. Das Fragment hält das Token aus den Serverprotokollen heraus und ist daher vorzuziehen.
Claims
Claim | Erforderlich | Bedeutung |
|---|---|---|
| Ja | Ihre stabile Nutzer-ID. Sie identifiziert den Leser bei jeder Anmeldung. |
| Ja | Die E-Mail-Adresse des Lesers. |
| Ja | Zeitpunkt, zu dem Sie das Token signiert haben. |
| Ja | Zeitpunkt des Ablaufs. |
| Nein | Der Anzeigename des Lesers. |
| Nein | Eine HTTPS-Bild-URL, die als Avatar des Lesers verwendet wird. |
| Nein | Attribute für Gruppenregeln, siehe unten. |
Tokenregeln
Signieren Sie mit HS256. HS384 und HS512 werden ebenfalls akzeptiert.
Ein Token wird höchstens 15 Minuten nach seinem
iatakzeptiert, unabhängig davon, wasexpangibt. Eine Abweichung der Systemuhren wird nicht berücksichtigt.Ein Token, das über die Weiterleitung zurückgegeben wird, kann nur einmal verwendet werden.
issundaudwerden nicht überprüft.Wenn für ein neues
subeine E-Mail-Adresse verwendet wird, die bereits einem anderen Leser gehört, schlägt die Anmeldung fehl. Bei einem bekanntensubwird die E-Mail-Adresse des Lesers aktualisiert, wenn sie neu ist – es sei denn, ein anderer Leser verwendet diese Adresse bereits.
Der Signaturschlüssel
Ferndesk generiert den Schlüssel: Wählen Sie unter Single Sign-on die Option Schlüssel generieren. Inhaber und Administratoren können ihn dort oder unter Einstellungen > Arbeitsbereich > Entwickler im Bereich Kundenanmeldung anzeigen und neu generieren. Es ist derselbe Schlüssel. Wenn Sie ihn neu generieren, ist eine Anmeldung erst wieder möglich, wenn Ihre App den neuen Schlüssel verwendet. Mit Anmeldung testen wird der gesamte Ablauf einmal ausgeführt, sobald ein Schlüssel und eine Anmelde-URL festgelegt sind.
Ohne Weiterleitung anmelden
Um einen Leser innerhalb Ihres Produkts anzumelden, senden Sie POST /api/auth/identify an die Domain Ihres Help Centers und übergeben den JSON-Body {"jwt": "TOKEN"}. Das Widget SDK erledigt dies für das Widget. Unter Weitere Optionen können Sie eine Abmelde-URL festlegen. Leser, die sich über Ihre App angemeldet haben, werden beim Abmelden dorthin weitergeleitet; return_to wird dabei hinzugefügt.
Attribute und Gruppenregeln
Attribute in metadata werden für den Leser gespeichert und bei jeder Anmeldung ersetzt. Gruppenregeln gleichen die Attribute ab; alle Bedingungen einer Regel müssen erfüllt sein.
Werte können Zeichenfolgen (bis zu 256 Zeichen), Zahlen, boolesche Werte oder Listen mit Elementen eines dieser Typen sein (bis zu 64 Elemente).
Verschachtelte Objekte werden bis zu einer Tiefe von 4 Ebenen in Punktpfade umgewandelt:
{"features": {"sso": true}}wird zufeatures.sso.Nach dem Abflachen sind bis zu 32 Attribute zulässig. Ein JWT mit einem ungültigen Attribut wird abgelehnt.
Operator | Bedingung |
|---|---|
ist, ist einer von | Das Attribut entspricht dem Wert oder einem der Werte. Bei einer Liste kann ein beliebiges Element übereinstimmen. |
enthält | Eine Liste enthält den Wert als Element oder eine Zeichenfolge enthält ihn. |
ist nicht, ist keiner von, schließt aus | Das Gegenteil des passenden Operators, sofern das Attribut festgelegt ist. |
ist festgelegt, ist nicht festgelegt | Das Attribut ist vorhanden oder fehlt. |
Ein fehlendes Attribut entspricht nur ist nicht festgelegt. Regelwerte werden als Text eingegeben: true und false entsprechen booleschen Werten, und eine Zahl entspricht einem Zahlenattribut.
OIDC
Öffnen Sie unter Besucheranmeldung den Bereich Single Sign-On (OIDC) und geben Sie die Discovery-URL, die Client-ID und das Client-Secret Ihres Anbieters ein. Erlauben Sie bei Ihrem Anbieter folgende Weiterleitungs-URI:
https://<your help center domain><base path>/api/auth/oidc/callbackFerndesk verwendet den Authorization-Code-Flow mit PKCE, fordert
openid,profileundemailan und sendet das Client-Secret im Body der Token-Anfrage.Die Discovery-URL muss öffentlich zugänglich sein und
issuer,authorization_endpoint,token_endpointundjwks_uriaufführen. Der Issuer des ID-Tokens muss damit übereinstimmen, und seine Audience muss der Client-ID entsprechen.Das ID-Token benötigt
subundemail. Der Name wird ausnameund anschließend auspreferred_usernameübernommen.Ein vorhandener Leser wird nur dann anhand der E-Mail-Adresse zugeordnet, wenn der Anbieter
email_verifiedsetzt.Jeder andere Claim, etwa
groups, wird zu einem Leserattribut für Gruppenregeln. Claims zur Anmeldung selbst, etwaauth_time,jtiundemail_verified, werden nicht gespeichert.Ein Leser kann bis zu 32 Attribute haben. Eigene Claims werden zuerst berücksichtigt; standardmäßige Profil-Claims wie
given_nameundlocalefüllen die verbleibenden Plätze. Ungültige Claims werden verworfen.Beim Abmelden wird nur die Sitzung des Help Centers beendet, nicht die Sitzung beim Anbieter.
Fehlerbehebung
Wenn eine Anmeldung über eine Weiterleitung fehlschlägt, wird den Lesern unabhängig von der Ursache Anmeldung fehlgeschlagen angezeigt. Um den Grund herauszufinden, senden Sie dasselbe Token an POST /api/auth/identify: Das Feld error enthält eine der folgenden Meldungen.
„Dieser Anmeldelink wurde bereits verwendet“
„Ungültiges oder abgelaufenes Token“
Die Signatur stimmt nicht mit dem Signaturschlüssel überein, das Token ist abgelaufen oder wurde vor mehr als 15 Minuten signiert. Signieren Sie es unmittelbar vor der Weiterleitung mit dem aktuellen Schlüssel und halten Sie die Serveruhr synchron.
„JWT abgelaufen oder exp-Claim fehlt“
Das Token enthält keinen exp-Claim. Fügen Sie einen hinzu.
„Das JWT-Subject stimmt nicht mit dem vorhandenen Help-Center-Benutzer überein“
Ein anderer Leser mit einem abweichenden sub verwendet bereits diese E-Mail-Adresse. Sorgen Sie dafür, dass sub für jede Person stabil bleibt.
„JWT-Metadaten sind zu groß oder ungültig“
Ein Attribut überschreitet die oben genannten Grenzwerte, zum Beispiel ein Nullwert oder eine Liste mit unterschiedlichen Datentypen.
OIDC meldet „Single Sign-on wurde nicht abgeschlossen“
Überprüfen Sie die Client-ID und das Client-Secret, ob der Anbieter die Weiterleitungs-URI und die Methode client_secret_post zulässt und ob das ID-Token sub und email enthält.