Stel single sign-on (SSO) in voor uw helpcentrum.

Meld lezers aan bij uw helpcentrum vanuit uw app met een SSO-URL, via Messenger of een omleiding vanaf uw server.

8 min lezen

Wanneer een lezer die niet is ingelogd uw helpcentrum opent, stuurt Notiondesk hem of haar door naar een pagina van uw app, uw SSO-URL. Op die pagina wordt de lezer ingelogd met Messenger of via een redirect vanaf uw server, waarna hij of zij terugkeert naar de pagina waar hij of zij om vroeg, zonder opnieuw te hoeven inloggen.

Snelkoppeling: ga naar Instellingen > Toegang , selecteer Gastaccounts en voer vervolgens de pagina van uw app in bij SSO-URL .

Voordat je begint

  • Uw helpcentrum maakt gebruik van de toegangsmodus voor gastaccounts .
  • Je hebt een app-geheim. Maak er een aan in Instellingen > Toegang , in het tabblad App-geheim . Het wordt maar één keer weergegeven, dus sla het op je server op, bijvoorbeeld in NOTIONDESK_APP_SECRET.
  • Uw server kan een gebruikerstoken ondertekenen. Identificeer ingelogde gebruikers in Messenger. Messenger legt het token uit. In Instellingen > Widget geeft de kaart 'Gebruikersinformatie synchroniseren ' de ondertekeningscode in Node.js, Python, PHP en Ruby, waarbij uw site_uuid is ingevuld. Sla die site_uuid ook op uw server op, bijvoorbeeld in NOTIONDESK_SITE_UUID.
Onderteken het token nooit in de browser. Iedereen die uw App Secret heeft, kan inloggen als elke lezer van uw helpcentrum.

Stap 1: Voeg uw SSO-URL toe

  1. Ga naar Instellingen > Toegang .
  1. Ga naar Toegangsbeheer en stel de toegangsmodus in op Gastaccounts . Deze wijziging wordt direct opgeslagen.
  1. Voer bij SSO-URL het adres in van de pagina van uw app waarmee lezers zich aanmelden, bijvoorbeeld https://app.example.com/help-sso.
  1. Klik op Wijzigingen opslaan .

De SSO-URL moet beginnen met https://, een domeinnaam gebruiken (niet localhost) en een pagina van uw app zijn, niet van uw helpcentrum. Als uw helpcentrum zich op uw eigen domein bevindt, gebruik dan een andere host, of dezelfde host buiten het pad van het helpcentrum: als uw helpcentrum zich op example.com/help bevindt, werkt example.com/login.

Wanneer Notiondesk een lezer naar uw SSO-URL stuurt, behoudt het uw eigen queryreeks en voegt return_to toe, het volledige adres van de helpcentrum-pagina waar de lezer om heeft gevraagd. Het voegt ook twee parameters toe die Messenger gebruikt. Laat deze in de URL staan.

Stap 2: Meld lezers aan op uw SSO-pagina.

Kies de optie die het beste bij uw app past. Beide opties gebruiken hetzelfde gebruikerstoken.

Optie A: met de Messenger

Gebruik deze optie als uw app al Messenger gebruikt. Laad op uw SSO-pagina Messenger met een gebruikerstoken voor de ingelogde gebruiker. Messenger meldt de lezer aan bij uw helpcentrum en stuurt hem of haar terug naar de pagina die is opgevraagd. Er zijn verder geen verdere functies nodig.

Zorg ervoor dat uw SSO-pagina:

  • Meld de gebruiker eerst aan bij uw app. Een bezoeker zonder gebruikerstoken is niet aangemeld bij het helpcentrum.
  • Laadt de Messenger van het helpcentrum waar de lezer vandaan komt, met een token dat is ondertekend met het App Secret van dat helpcentrum.
  • De token wordt ondertekend bij het laden van de pagina, met een geldigheidsduur van maximaal één uur. Een latere geldigheidsduur wordt geweigerd.
  • Opent als een normale pagina, niet in een frame, en stelt de apiUrl-optie van Messenger niet in.
  • Het behoudt het volledige adres waarmee het is geopend. Als uw inlogprocedure de gebruiker eerst naar een andere site of tabblad stuurt, breng hem dan terug naar datzelfde adres, inclusief alle parameters, voordat Messenger wordt geladen.

De documentatie van de Messenger SDK beschrijft de installatie van React, Vue en scripttags in het gedeelte 'Aanmelden' van het Helpcentrum .

Optie B: met een omleiding vanaf uw server.

Gebruik deze optie als uw app Messenger niet gebruikt, of als u lezers liever op uw server wilt laten inloggen.

  1. Lees op je SSO-pagina return_to uit het adres en bewaar dit tijdens het inloggen.
  1. Onderteken op uw server een gebruikerstoken voor de ingelogde gebruiker met uw App Secret.
  1. De browser wordt doorgestuurd naar https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO, met het domein van uw helpcentrum, het token en return_to, beide URL-gecodeerd. Bij een helpcentrum op example.com/help begint het adres met https://example.com/help/private/sso/jwt.

Hier is een voorbeeld in Node.js met Express. requireLogin staat voor je eigen inlogcontrole: het stuurt een uitgelogde gebruiker naar je inlogpagina en vervolgens terug naar dit adres met de bijbehorende queryreeks.

Houd deze regels in gedachten:

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());
});
  • Voor elke omleiding moet een nieuw token worden aangemaakt. Een token meldt een gebruiker eenmalig aan.
  • Geef het een korte geldigheidsduur. 5 minuten is voldoende, en een tijdsverschil van meer dan een uur wordt geweigerd. Zorg ervoor dat de klok van uw server gesynchroniseerd is: een verschil van maximaal 60 seconden is acceptabel.
  • Houd het token onder de 8 KB, dus houd alle custom_attributes klein.
  • Stuur return_to ongewijzigd terug. Zonder dit veld, of met een adres buiten uw helpcentrum, komt de lezer terecht op de homepage van het helpcentrum.
  • Doorverwijzing vanaf uw server. Plaats deze link nooit in een e-mail, aangezien het token in het adres is opgenomen.

Je kunt gebruikers ook rechtstreeks vanuit je app naar dit adres sturen zonder SSO-URL, bijvoorbeeld via een Help- link in het menu van je app. Stel return_to in op de helpcentrum-pagina die je wilt dat ze openen.

Stap 3: Test het

  1. Open een privévenster in uw browser en ga naar een pagina van uw helpcentrum waarvoor u moet inloggen.
  1. Controleer of u op uw SSO-URL terechtkomt, inlogt bij uw app en vervolgens, ingelogd, terugkeert naar dezelfde helpcentrum-pagina.

Als het niet werkt, controleer dan een token dat uw app ondertekent:

  1. Ga naar Instellingen > Toegang en klik onder SSO-URL op 'Een aanmeldingstoken controleren' . Deze optie verschijnt zodra een SSO-URL is opgeslagen.
  1. Plak het token en klik vervolgens op 'Token controleren' . Je ziet dan of je helpcentrum het accepteert en waarom niet. Het token wordt gecontroleerd, maar nooit opgeslagen.

Bepaal wanneer lezers naar uw SSO-URL gaan.

De optie 'Aanmelden vereisen' , de schakelaar boven 'SSO-URL' , is standaard ingeschakeld. Hierdoor wordt elke lezer die niet is aangemeld, doorgestuurd naar uw SSO-URL wanneer hij of zij uw helpcentrum opent.

Als deze functie is uitgeschakeld, kan iedereen uw helpcentrum bezoeken en worden alleen deze lezers doorgestuurd naar uw SSO-URL:

  • Lezers die een artikel openen waarvoor een aanmelding vereist is.
  • Lezers die een link naar het helpcentrum volgen die eindigt op nd_sign_in=1, zoals https://help.example.com/en/articles/billing?nd_sign_in=1, kunnen deze link toevoegen aan de links naar het helpcentrum in hun app.
  • Lezers die op ' Doorgaan met uw account ' klikken op de aanmeldpagina van het helpcentrum.

Gasten die je hebt uitgenodigd, kunnen op de aanmeldpagina nog steeds kiezen voor 'E-mail en wachtwoord gebruiken' .

Link lezers naar gastaccounts die u hebt uitgenodigd.

Een token voor een gebruiker die u nooit hebt uitgenodigd, meldt deze gebruiker aan als nieuwe lezer. Om een ​​gebruiker toegang en de rol te geven van een gastaccount dat u per e-mail hebt uitgenodigd:

  • Voeg de parameter email van de gebruiker toe aan het token vanaf het moment dat u de gebruiker voor het eerst identificeert. Een gebruiker die in eerste instantie zonder deze parameter wordt geïdentificeerd, behoudt een aparte lezer, zonder de toegang van het gastaccount, zelfs als u het e-mailadres later toevoegt.
  • Als uw app het e-mailadres van een gebruiker nog niet heeft geverifieerd, stuur dan email_verified: false. Die gebruiker is niet gekoppeld aan het gastaccount. Als u dit weglaat, wordt het e-mailadres als geverifieerd beschouwd. Stuur het als true of false, niet als tekst: een waarde zoals "true" telt als false.
  • Een gastaccount is gekoppeld aan één user_id. Een tweede gebruiker die inlogt met hetzelfde e-mailadres, behoudt een aparte lezer.

Als de uitnodiging van de gast nog in behandeling was, wordt deze automatisch geaccepteerd.

Probleemoplossing

Probleem Oorzaak Repareren
De lezer komt terecht op de inlogpagina met de melding: "Het is ons niet gelukt u automatisch in te loggen. Probeer het opnieuw of log hieronder in." Het token werd geweigerd: het was verlopen, was al in gebruik, verloopt over meer dan een uur of was ondertekend met een ander App Secret. Voer een controle uit op het aanmeldingstoken en genereer een nieuw token voor elke omleiding.
De lezer blijft op uw SSO-pagina. Messenger had geen gebruikerstoken of een ongeldig token, het adres verloor zijn parameters tijdens het inloggen, de pagina bevindt zich in een frame, of apiUrl is ingesteld. Voer ' Controleer een aanmeldingstoken' uit en controleer de lijst in optie A.
De lezer is ingelogd, maar komt toch op de homepage terecht. return_to ontbrak of is geen pagina van uw helpcentrum. Geef return_to ongewijzigd terug
Lezers worden nooit doorgestuurd naar uw SSO-URL. Er is geen SSO-URL opgeslagen, of 'Aanmelden verplicht' is uitgeschakeld. Sla een SSO-URL op en voeg vervolgens nd_sign_in=1 toe aan de links in uw helpcentrum of schakel ' Aanmelden vereisen' in.
"Voer een URL in die begint met https://" wanneer u opslaat De SSO-URL is geen https://-adres Gebruik het adres https:// van een pagina van uw app.
"Ga naar een pagina van uw app, niet van uw helpcentrum." wanneer u opslaat De SSO-URL vindt u in het adres van uw helpcentrum. Gebruik een andere host of een pad buiten het helpcentrum.
Controleer of een aanmeldingstoken de melding "Dit token is nog niet geldig" geeft. iat wordt weergegeven in milliseconden, of de klok van uw server loopt voor. Gebruik seconden en synchroniseer de klok van je server.
Een lezer krijgt geen toegang tot het gastaccount dat u hebt uitgenodigd. Het token had de eerste keer geen email, of email_verified is niet __GERESERVEERD_2__ Zie 'Lezers koppelen aan gastaccounts die u hebt uitgenodigd' hierboven.

Veelgestelde vragen

Worden lezers twee keer ingelogd?

Nee. Lezers die zich aanmelden bij uw app, gaan via uw SSO-URL en keren terug als ingelogd, zonder een Notiondesk login.

Welke optie moet ik kiezen?

Optie A als uw app Messenger al uitvoert op een pagina die u beheert. Optie B als dit niet het geval is, of als uw inlogproces op uw eigen server draait.

Kunnen lezers zich nog steeds aanmelden met een e-mailadres en wachtwoord?

Ja. Gasten die u hebt uitgenodigd, kunnen op de aanmeldpagina van het helpcentrum kiezen voor 'E-mail en wachtwoord gebruiken' .

Hoe lang blijft een lezer ingelogd?

Tot wel 12 uur. Als je uitlogt bij je app, word je niet automatisch uitgelogd bij het helpcentrum, dus houd daar rekening mee op gedeelde computers.

Wie mag de SSO-URL wijzigen?

Eigenaren van werkruimtes, beheerders en redacteuren.

Hoe schakel ik SSO uit?

Wis het veld SSO-URL en klik op Wijzigingen opslaan . Lezers kunnen vervolgens inloggen met hun e-mailadres en wachtwoord.

Gerelateerde artikelen

Was deze pagina nuttig?

Still need help? Ask us