○ SSO - Workflow en problemen oplossen
Voor het SSO-proces heb je een API integratie nodig. Als een deelnemer via SSO wil inloggen, zou je moeten beginnen met deze API call:
GET /getLoginToken/{userID}
Je moet hiervoor de externe ID of de UID van de gebruiker gebruiken. Bijvoorbeeld:
Voorbeeld van getLoginToken met extern ID
GET http(s)://<domein>/api/getLoginToken/1234
Voorbeeld van getLoginToken met UID
GET http(s)://<domein>/api/getLoginToken?userUID=c21f7c68-7682-11eb-b67e-06575dd7e8c5
De login token kan maar één keer gebruikt worden, zorg er dus voor dat deelnemers niet meer dan één keer worden doorverwezen met dezelfde login token. Dat veroorzaakt namelijk een foutmelding voor de deelnemer.
Een goede werkwijze waarbij je dit kunt voorkomen, zou zijn om de login token pas op te vragen nadat een deelnemer op een link klikt die SSO in gang moet zetten.
Alleen de meest recente login token van een gebruiker is geldig.
Wanneer je de login token hebt opgevraagd, kan SSO worden uitgevoerd door een redirect naar de browser te sturen: http(s)://<domein>/do?action=sso
<domein> moet worden vervangen door het domein van de leeromgeving.
Je kunt de volgende parameters toevoegen (* is verplicht):
- user*: Dit is de externe ID van de gebruiker. Het is alleen verplicht als userUID niet wordt meegegeven.
- userUID*: Dit is de UID van de gebruiker. Het is alleen verplicht als user niet wordt meegegeven.
- token*: Dit is de login token die je via de API hebt opgehaald.
- course: Door deze parameter toe te voegen, kun je na het inloggen met SSO automatisch het activiteitenoverzicht laten openen van cursussen waar de deelnemer een inschrijving voor heeft. Je moet hiervoor de externe ID van de uitvoering gebruiken.
Deze parameter kan niet worden gecombineerd met de redirect parameter. - activity: Door deze parameter toe te voegen, kun je na het inloggen met SSO automatisch een specifieke activiteit openen van een cursus waar de deelnemer een inschrijving voor heeft. Je moet hiervoor de externe ID van de activiteit gebruiken. Dit werkt alleen als de course parameter ook aanwezig is.
- redirect: Door deze parameter toe te voegen, kun je na het inloggen met SSO automatisch een (relatieve) URL van de leeromgeving laten openen. Dit kan worden ingezet om gebruikers naar een pagina te verwijzen aan de hand van een link in een e-mailnotificatie. (Meer informatie)
Deze parameter moet niet worden gecombineerd met de course en activity parameters.
Voorbeeld:
GET https://<domain>/do?action=sso&user=1234&token=24345226-ec3a-4d90-a5d0-aa99c80ec491
Voorbeeld met parameters course en activity:
GET https://<domain>/do?action=sso&user=1234&token=24345226-ec3a-4d90-a5d0-aa99c80ec491&course=course01&activity=activity01
Voorbeeld met parameter redirect:
GET https://<domain>/do?action=sso&user=1234&token=24345226-ec3a-4d90-a5d0-aa99c80ec491&redirect=%2Fdo%3Faction%3Dplayer%26type%3DLesson%26id%3D1234%26courseId%3D1234
Problemen oplossen
Dit zijn veelvoorkomende foutmeldingen die je gebruikers kunnen krijgen als er iets misgaat bij het inloggen via SSO:
- Incorrect token
Deze foutmelding betekent dat de login token niet hetzelfde is als de meest recent gegenereerde token voor die gebruiker. Een goede manier om dit te voorkomen is het opvragen van de login token pas te laten gebeuren vlak voordat SSO daadwerkelijk wordt uitgevoerd en oude tokens niet op te slaan. - Parameter 'token' is empty
Dit betekent dat de login token niet aanwezig is in de SSO URL. - User has no login token
Dit betekent dat de meest recent gegenereerde login token al is gebruikt en dat de integratie eerst een nieuwe login token moet opvragen. Een goede manier om dit te voorkomen is het opvragen van de login token pas te laten gebeuren vlak voordat SSO daadwerkelijk wordt uitgevoerd. - User is not subscribed to course
Dit betekent dat de gebruiker niet is ingeschreven voor de uitvoering waar naar wordt verwezen in de SSO URL. Dit kan worden voorkomen door na te gaan of de inschrijving al bestaat d.m.v. de API call /isSubscribed/{userID}/{courseID}. Je kunt de API ook gebruiken om de deelnemer voor de cursus in te schrijven: /subscribe/{userID}/{courseID}