Richten Sie Single Sign-On (SSO) für Ihr Hilfezentrum ein.

Melden Sie Leser über Ihre App mit einer SSO-URL, über den Messenger oder eine Weiterleitung von Ihrem Server in Ihrem Hilfecenter an.

8 Min. Lesezeit

Wenn ein nicht angemeldeter Nutzer Ihr Hilfecenter öffnet, leitet Notiondesk ihn auf eine Seite Ihrer App weiter, Ihre SSO-URL. Dort meldet er sich entweder über den Messenger oder per Weiterleitung von Ihrem Server an und gelangt ohne erneute Anmeldung wieder auf die gewünschte Seite.

Schnellzugriff: Gehen Sie zu Einstellungen > Zugriff , wählen Sie Gastkonten aus und geben Sie dann eine Seite Ihrer App unter SSO-URL ein.

Bevor Sie beginnen

  • Ihr Hilfecenter verwendet den Gastzugriffsmodus .
  • Sie besitzen ein App-Geheimnis. Erstellen Sie eines unter Einstellungen > Zugriff auf der Karte „App-Geheimnis“ . Es wird nur einmal angezeigt, speichern Sie es daher auf Ihrem Server, beispielsweise in NOTIONDESK_APP_SECRET.
  • Ihr Server kann ein Benutzertoken signieren. Angemeldete Benutzer werden in Notiondesk identifiziert. Messenger erklärt das Token. Unter Einstellungen > Widget bietet die Karte „Benutzerinformationen synchronisieren“ Signaturcode in Node.js, Python, PHP und Ruby, wobei Ihre site_uuid bereits ausgefüllt sind. Speichern Sie diese site_uuid ebenfalls auf Ihrem Server, beispielsweise in NOTIONDESK_SITE_UUID.
Signieren Sie das Token niemals im Browser. Jeder, der Ihr App-Geheimnis kennt, kann sich als beliebiger Leser Ihres Hilfecenters anmelden.

Schritt 1: Fügen Sie Ihre SSO-URL hinzu

  1. Gehen Sie zu Einstellungen > Zugriff .
  1. Stellen Sie unter Zugriffskontrolle den Zugriffsmodus auf Gastkonten ein. Die Einstellung wird sofort gespeichert.
  1. Geben Sie im Feld SSO-URL die Adresse der Seite Ihrer App ein, auf der sich Leser anmelden, zum Beispiel https://app.example.com/help-sso.
  1. Klicken Sie auf „Änderungen speichern“ .

Die SSO-URL muss mit https:// beginnen, einen Domänennamen (nicht localhost) verwenden und zu Ihrer Anwendung gehören, nicht zu Ihrem Hilfecenter. Befindet sich Ihr Hilfecenter auf Ihrer eigenen Domäne, verwenden Sie einen anderen Host oder denselben Host außerhalb des Pfads des Hilfecenters: Wenn sich Ihr Hilfecenter unter example.com/help befindet, funktioniert example.com/login.

Wenn Notiondesk einen Leser zu Ihrer SSO-URL weiterleitet, behält es Ihre eigene Abfragezeichenfolge bei und fügt return_to hinzu, die vollständige Adresse der Hilfeseite, die der Leser angefordert hat. Außerdem fügt es zwei vom Messenger verwendete Parameter hinzu. Lassen Sie diese in der URL.

Schritt 2: Melden Sie Leser auf Ihrer SSO-Seite an

Wählen Sie die Option, die zu Ihrer App passt. Beide verwenden dasselbe Benutzertoken.

Option A: mit dem Boten

Nutzen Sie diese Option, wenn Ihre App bereits den Messenger verwendet. Laden Sie auf Ihrer SSO-Seite den Messenger mit einem Benutzertoken für den angemeldeten Benutzer. Der Messenger meldet den Leser in Ihrem Hilfecenter an und leitet ihn zurück zur gewünschten Seite. Es ist kein weiterer Aufruf erforderlich.

Stellen Sie sicher, dass Ihre SSO-Seite:

  • Meldet den Benutzer zunächst in Ihrer App an. Ein Besucher ohne Benutzertoken ist nicht im Hilfecenter angemeldet.
  • Lädt den Messenger des Hilfezentrums, von dem der Leser kam, mit einem Token, das mit dem App-Geheimnis dieses Hilfezentrums signiert ist.
  • Das Token wird beim Laden der Seite signiert und ist maximal eine Stunde gültig. Eine längere Gültigkeitsdauer wird abgelehnt.
  • Öffnet sich als normale Seite, nicht in einem Frame, und setzt die Option apiUrl des Messengers nicht.
  • Die vollständige Adresse, mit der die Seite geöffnet wurde, wird beibehalten. Falls der Benutzer nach dem Login zunächst auf eine andere Website oder einen anderen Tab weitergeleitet wird, wird er vor dem Laden des Messengers wieder auf dieselbe Adresse mit allen zugehörigen Parametern zurückgeführt.

Die Messenger SDK-Dokumentation behandelt die Installation von React, Vue und Script-Tags im Anmeldebereich des Hilfecenters .

Option B: mit einer Weiterleitung von Ihrem Server

Nutzen Sie diese Option, wenn Ihre App den Messenger nicht ausführt oder wenn Sie die Leser lieber auf Ihrem Server anmelden möchten.

  1. Lesen Sie auf Ihrer SSO-Seite return_to aus der Adresse aus und behalten Sie diese Information für Ihre Anmeldung bei.
  1. Signieren Sie auf Ihrem Server ein Benutzertoken für den angemeldeten Benutzer mit Ihrem App-Geheimnis.
  1. Leiten Sie den Browser auf https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO um, wobei die Domain Ihres Hilfezentrums, das Token und return_to URL-codiert sind. Bei einem Hilfezentrum unter example.com/help beginnt die Adresse mit https://example.com/help/private/sso/jwt.

Hier ist ein Beispiel in Node.js mit Express. requireLogin steht für Ihre eigene Anmeldeprüfung: Sie leitet einen abgemeldeten Benutzer auf Ihre Anmeldeseite und anschließend mit seiner Abfragezeichenfolge zurück an diese Adresse.

Beachten Sie bitte folgende Regeln:

const jwt = require('jsonwebtoken');

const HELP_CENTER_URL = 'https://help.example.com';

app.get('/help-sso', requireLogin, (req, res) => {
  const now = Math.floor(Date.now() / 1000);
  const token = jwt.sign(
    {
      type: 'site_contact_app',
      iat: now,
      exp: now + 300,
      user_id: String(req.user.id),
      site_uuid: process.env.NOTIONDESK_SITE_UUID,
      email: req.user.email,
      name: req.user.name,
    },
    process.env.NOTIONDESK_APP_SECRET,
    { algorithm: 'HS256' },
  );

  const target = new URL(`${HELP_CENTER_URL}/private/sso/jwt`);
  target.searchParams.set('jwt', token);
  if (req.query.return_to) {
    target.searchParams.set('return_to', req.query.return_to);
  }
  res.redirect(target.toString());
});
  • Für jede Weiterleitung muss ein neues Token generiert werden. Ein Token dient nur zur einmaligen Anmeldung eines Lesers.
  • Setzen Sie eine kurze Gültigkeitsdauer. 5 Minuten genügen, mehr als eine Stunde wird nicht akzeptiert. Stellen Sie sicher, dass die Serveruhr synchron läuft: Eine Abweichung von bis zu 60 Sekunden ist zulässig.
  • Halten Sie das Token unter 8 KB, also halten Sie alle custom_attributes klein.
  • Geben Sie return_to unverändert zurück. Ohne diese Angabe oder mit einer Adresse außerhalb Ihres Hilfezentrums gelangt der Leser auf die Startseite des Hilfezentrums.
  • Leiten Sie von Ihrem Server um. Fügen Sie diesen Link niemals in eine E-Mail ein, da sich das Token in der Adresse befindet.

Sie können Nutzer auch direkt von Ihrer App zu dieser Adresse weiterleiten, ohne eine SSO-URL zu verwenden, beispielsweise über einen Hilfelink im Menü Ihrer App. Legen Sie return_to auf die Hilfeseite fest, die geöffnet werden soll.

Schritt 3: Testen Sie es

  1. Öffnen Sie ein privates Browserfenster und rufen Sie eine Seite Ihres Hilfecenters auf, für die eine Anmeldung erforderlich ist.
  1. Prüfen Sie, ob Sie auf Ihrer SSO-URL landen, sich in Ihrer App anmelden und anschließend angemeldet zur selben Hilfeseite zurückkehren.

Falls es nicht funktioniert, überprüfen Sie das Token, das Ihre App signiert:

  1. Klicken Sie unter Einstellungen > Zugriff > SSO-URL auf Anmeldetoken prüfen . Diese Option wird angezeigt, sobald eine SSO-URL gespeichert wurde.
  1. Fügen Sie das Token ein und klicken Sie dann auf „Token prüfen“ . Sie sehen dann, ob Ihr Hilfecenter es akzeptiert und warum nicht. Das Token wird geprüft und niemals gespeichert.

Wählen Sie aus, wann Leser Ihre SSO-URL aufrufen.

Die Option „Anmeldung erforderlich“ (über der SSO-URL ) ist standardmäßig aktiviert. Wenn diese Option aktiviert ist, wird jeder nicht angemeldete Nutzer beim Öffnen Ihres Hilfecenters zu Ihrer SSO-URL weitergeleitet.

Wenn diese Funktion deaktiviert ist, kann jeder Ihr Hilfecenter durchsuchen, und nur diese Leser werden an Ihre SSO-URL weitergeleitet:

  • Leser, die einen Artikel öffnen, für den eine Anmeldung erforderlich ist.
  • Leser, die einem Hilfe-Link folgen, der mit nd_sign_in=1 endet, wie z. B. https://help.example.com/en/articles/billing?nd_sign_in=1. Fügen Sie diesen Link zu den Hilfe-Links in Ihrer App hinzu.
  • Leser, die auf der Anmeldeseite des Hilfecenters auf „Mit Ihrem Konto fortfahren“ klicken.

Eingeladene Gäste können weiterhin die Option „E-Mail-Adresse und Passwort verwenden“ auf der Anmeldeseite auswählen.

Verlinke Leser mit den von dir eingeladenen Gastkonten.

Ein Token für einen Benutzer, den Sie nie eingeladen haben, meldet ihn als neuen Leser an. Um einem Benutzer die Zugriffsrechte und die Rolle eines Gastkontos zuzuweisen, zu dem Sie ihn per E-Mail eingeladen haben:

  • Fügen Sie die email-Kennung des Benutzers bereits bei dessen erstmaliger Identifizierung in das Token ein. Ein Benutzer, der zunächst ohne diese Kennung identifiziert wurde, behält einen separaten Reader ohne Zugriff auf das Gastkonto, selbst wenn Sie die E-Mail-Adresse später hinzufügen.
  • Wenn Ihre App die E-Mail-Adresse eines Nutzers nicht verifiziert hat, senden Sie email_verified: false. Dieser Nutzer ist nicht mit dem Gastkonto verknüpft. Wenn Sie die E-Mail-Adresse weglassen, gilt sie als verifiziert. Senden Sie sie als true oder false, nicht als Text: Ein Wert wie "true" wird als false gezählt.
  • Ein Gastkonto ist mit einem user_id verknüpft. Ein zweiter Benutzer, der sich mit derselben E-Mail-Adresse anmeldet, behält einen separaten Reader.

Falls die Einladung des Gastes noch ausstand, wird sie automatisch angenommen.

Fehlerbehebung

Problem Ursache Fix
Der Leser gelangt auf die Anmeldeseite mit der Meldung: „Wir konnten Sie nicht automatisch anmelden. Versuchen Sie es erneut oder melden Sie sich unten an.“ Das Token wurde abgelehnt: Es war abgelaufen, wurde bereits verwendet, läuft in mehr als einer Stunde ab oder wurde mit einem anderen App-Geheimnis signiert. Führen Sie eine Überprüfung des Anmeldetokens durch und signieren Sie für jede Weiterleitung ein neues Token.
Der Leser bleibt auf Ihrer SSO-Seite. Der Messenger verfügte über kein oder ein ungültiges Benutzertoken, die Adressparameter gingen beim Login verloren, die Seite befindet sich in einem Frame oder apiUrl ist gesetzt. Führen Sie „Anmeldetoken prüfen“ aus und prüfen Sie die Liste in Option A.
Der Leser ist angemeldet, landet aber auf der Startseite. Die Seite return_to fehlt oder ist keine Seite Ihres Hilfezentrums. Passe return_to unverändert zurück.
Leser werden niemals an Ihre SSO-URL weitergeleitet. Es ist keine SSO-URL gespeichert, oder die Option „Anmeldung erforderlich“ ist deaktiviert. Speichern Sie eine SSO-URL und fügen Sie dann nd_sign_in=1 zu Ihren Hilfecenter-Links hinzu oder aktivieren Sie die Option „Anmeldung erforderlich“.
"Geben Sie beim Speichern eine URL ein, die mit https:// beginnt." Die SSO-URL ist keine https://-Adresse Verwenden Sie die https://-Adresse einer Seite Ihrer App.
„Geben Sie eine Seite Ihrer App ein, nicht die Ihres Hilfecenters.“ (beim Speichern) Die SSO-URL befindet sich in der Adresse Ihres Hilfecenters. Nutzen Sie einen anderen Host oder einen Pfad außerhalb des Hilfezentrums.
Die Meldung „Dieses Token ist noch nicht gültig“ wird angezeigt . iat wird in Millisekunden angegeben, oder die Uhr Ihres Servers geht voraus. Verwenden Sie Sekunden und synchronisieren Sie die Serveruhr.
Ein Leser erhält keinen Zugriff auf das von Ihnen eingeladene Gastkonto. Das Token hatte beim ersten Mal kein email, oder email_verified ist nicht vorhanden. true Siehe oben „Leser mit von Ihnen eingeladenen Gastkonten verknüpfen“.

Häufig gestellte Fragen

Melden sich Leser zweimal an?

Nein. Leser, die sich in Ihrer App anmelden, gehen über Ihre SSO-URL und kehren angemeldet zurück, ohne dass ein Notiondesk-Login erforderlich ist.

Welche Option soll ich wählen?

Option A, wenn Ihre App den Messenger bereits auf einer von Ihnen kontrollierten Seite ausführt. Option B, wenn dies nicht der Fall ist oder wenn Ihr Login auf Ihrem Server erfolgt.

Können sich Leser weiterhin mit E-Mail-Adresse und Passwort anmelden?

Ja. Eingeladene Gäste können auf der Anmeldeseite des Hilfecenters die Option „E-Mail-Adresse und Passwort verwenden“ auswählen.

Wie lange bleibt ein Leser angemeldet?

Bis zu 12 Stunden. Wenn Sie sich von Ihrer App abmelden, werden Sie nicht automatisch vom Hilfecenter abgemeldet. Beachten Sie dies bitte bei gemeinsam genutzten Computern.

Wer kann die SSO-URL ändern?

Arbeitsbereichsinhaber, Administratoren und Redakteure.

Wie deaktiviere ich SSO?

Leeren Sie das Feld „SSO-URL“ und klicken Sie auf „Änderungen speichern“ . Leser melden sich anschließend mit ihrer E-Mail-Adresse und ihrem Passwort an.

Verwandte Artikel

War diese Seite hilfreich?

Still need help? Ask us