Smartschool OAuth
Smartschool ondersteunt OAuth2. Laat gebruikers in je eigen webtoepassing aanmelden met hun Smartschoolaccount.
OAuth Flow
OAuth – Vragen en antwoorden
Wat houdt OAuth2 voor Smartschool in?
Smartschool ondersteunt OAuth2 als Identity provider. Hierdoor wordt het mogelijk een koppeling te leggen met een Smartschoolgebruiker. Eenmaal deze koppeling er is kunnen gegevens uitgewisseld en acties uitgevoerd worden voor deze Smartschoolgebruiker.
Kan OAuth gebruikt worden als single sign-on?
OAuth2 is een specificatie voor authorisatie, niet authenticatie.
- Authenticatie gaat over “wie is iemand”.
- Authorisatie gaat over “wie heeft toegang tot welke gegevens”.
Authorisatie-flows bevatten meestal een authenticatie als eerste stap, vandaar vaak de verwarring.
OAuth2 kan als authenticatie worden gebruikt, maar dat is buiten de scope van de specificatie. Hiervoor is steeds een eigen implementatie nodig.
In je eigen applicatie kan je dit bijvoorbeeld als volgt implementeren:
- Je voorziet een knop in je applicatie ‘Aanmelden met Smartschool’.
- Na het doorlopen van de authorisatie-flow, vraag je via de ‘userinfo endpoint’ gegevens op van de gebruiker waarin je onder andere zijn unieke Smartschool-identifier kan opvragen.
- Als er nog geen eigen gebruiker is met een relatie naar deze identifier, dan maak je deze aan en deze wordt dan aangemeld.
- Als er wel al een eigen gebruiker is met een relatie naar deze identifier, dan wordt deze rechtstreeks aangemeld in je applicatie.
Een voorbeeld van een soortgelijke oplossing (zonder dat er gebruikers aangemaakt worden) vind je terug in onze voorbeeldtoepassing.
Waarvoor dient de Redirect URI?
Dit is het webadres waarnaar de gebruiker wordt doorgestuurd nadat hij succesvol is aangemeld via Smartschool. Dit is dus de landingspagina van je toepassing die in de OAuth afhandeling moet worden voorzien. Deze URI dient publiek beschikbaar te zijn.
De redirect URI die je opgeeft voor je toepassing dient te beginnen met http of https. Vul steeds ook het volledige pad in en niet enkel je domeinnaam. Bijvoorbeeld: https://toepassing.school.be/login.php
De redirect URI die je opgeeft via redirect_uri=… in de OAuth flow moet EXACT overeenkomen met de redirect_uri die je eerder opgaf in het aanvraagformulier, inclusief https:// of https:// en eventueel verder pad van de url (/login.php).
Kunnen er meerdere Redirect URI’s opgeven worden voor één client?
Indien nodig mag je meerdere Redirect URI’s opgeven. Dit kan handig zijn wanneer je dezelfde client wilt gebruiken voor je ontwikkel-, acceptatie- en productieomgeving. We adviseren om dit zo te doen.
Overweeg ook het gebruik van de state parameter om gebruikers automatisch te routeren naar een bepaalde plaats in je eigen toepassing.
Kunnen er extra parameters meegegeven worden in de OAuth flow?
Je kan de optionele state parameter gebruiken bij het initialiseren van de OAuth flow.
Deze parameter krijg je ook terug nadat een gebruiker de OAuth flow heeft doorlopen. Door een bepaalde waarde in deze parameter op te nemen kan je eventueel verdere specifieke afhandeling binnen je eigen implementatie bouwen.
Deze parameter is dus onder meer geschikt om gebruikers automatisch te routeren naar een bepaalde plaats in je eigen toepassing.
Moet er per applicatie een aparte OAuth client aangevraagd worden?
Neen, je kan perfect dezelfde client gebruiken voor meerdere applicaties binnen je school of scholengemeenschap.
Moet er per Smartschoolplatform een aparte OAuth client aangevraagd worden?
Neen, per client kunnen we instellen voor welke platformen deze geldig is. Enkele opties:
- Client ABC mag connecteren naar Smartschoolplatform X.
- Client DEF mag connecteren naar Smartschoolplatform X, Y en Z.
- Client GHI mag connecteren naar alle Smartschoolplatformen.
Deze laatste optie is enkel interessant voor integratoren die diensten aanbieden voor grote groepen van scholen zoals platformen educatieve uitgevers.
Omwille van veiligheidsredenen adviseren we om de client niet breder te laten connecteren dan nodig.
Wat is het verschil tussen het leggen van een koppeling naar één of meerdere platformen?
Indien je enkel wenst te koppelen met 1 specifiek platform kan je best alle OAuth- en Api-calls naar hetzelfde platform sturen.
- Alle OAuth-calls dienen gemaakt te worden naar https://school.smartschool.be/OAuth
- Alle API-calls dienen gemaakt te worden naar https://school.smartschool.be/Api/V1/…
Indien je wenst te koppelen met meerdere platformen kan je alle calls naar het centrale platform oauth.smartschool.be sturen.
- Alle OAuth-calls dienen gemaakt te worden naar https://oauth.smartschool.be/OAuth
- Alle API-calls dienen gemaakt te worden naar https://oauth.smartschool.be/Api/V1/…
Deze flow loopt gelijkaardig met de flow van de koppeling met één platform op de uitzondering na dat de gebruiker eerst het webadres van zijn platform zal moeten ingeven.
Indien je een koppeling legt met meerdere platformen en je weet van welk platform de gebruiker is, kan je rechtstreeks de OAuth-fow initialiseren naar dat platform.
Waarom dien je een afbeelding van je toepassing aan te leveren?
We adviseren om ons een logo van je toepassing of organisatie te bezorgen welke we zullen tonen op de aanmeldpagina. Dit geeft de eindgebruiker een vertrouwd gevoel. Specificaties van dit logo: 156x156px zonder afronding in PNG-formaat en zonder transparantie.
Ondersteunt OAuth dubbele authenticatie?
Ja, indien een gebruiker dubbele authenticatie heeft geactiveerd zal hierom gevraagd worden tijdens het aanmelden.
Indien je OAuth wilt gebruiken voor WIFI-authenticatie kan je aan ons aangeven om deze extra beveiliging niet af te dwingen. Gebruik zulke OAuth client énkel voor WIFI, nooit voor gewone toepassingen.
Wat met OAuth als Smartschool gekoppeld is aan Google Apps of Office365?
Gebruikers die aanmelden met hun Google Apps- of Office 365-account kunnen dit ook doen binnen de OAuth-flow. Dit vormt geen enkel probleem.
Wat na het aanvragen van de OAuth client?
Je zal na het indienen van de OAuth aanvraag een client identifier en client secret ontvangen waarmee je aan de slag kan.
We raden je aan om eventueel gebruik te maken van een OAuth2 client die beschikbaar is voor de programmeertaal waarin je werkt. Meer info over clients is te vinden onder ‘Client Libraries’ op https://oauth.net/code
Welke scopes zijn beschikbaar?
Momenteel zijn er al meerdere scopes beschikbaar voor gebruik binnen de OAuth2 koppeling.
Indien je voor meerdere scopes goedkeuring wilt vragen aan de gebruiker, dien je deze in de OAuth flow mee te sturen gescheiden door spaties.
Voorbeeld: “/OAuth?client_id=[client_id]&redirect_uri=[redirect_uri]&response_type=code&scope=[scope1 scope2 scope3]”
Beschikbare scopes:
- userinfo: Opvragen van een deel van de profielgegevens (cross-platform identifier, platform-url, voornaam, naam en gebruikersnaam)
Voorbeeld: response leerling/leerkracht
Voorbeeld: response co-account (ouder) - fulluserinfo: Opvragen van de profielgegevens (bijvoorbeeld: cross-platform identifier, platform-url, voornaam, naam, gebruikersnaam, e-mailadres, telefoonnummer, geslacht, geboortedatum)
Voorbeeld: response co-account (ouder) - groupinfo: Opvragen van lidmaatschap van groepen en klassen
Voorbeeld: response leerling - sendmessage: Sturen van berichten (toepassing mag berichten sturen)
Deze scope is niet standaard toegestaan voor een nieuwe OAuth client, maar enkel op aanvraag. - sendnotif: Sturen van meldingen (toepassing mag meldingen sturen)
Deze scope is niet standaard toegestaan voor een nieuwe OAuth client, maar enkel op aanvraag.
Voorbeeld: sendmsg en sendnotif calls - Exerciseresults: Doorsturen van evaluaties en resultaten naar puntenboek.
Deze scope is niet standaard toegestaan voor een nieuwe OAuth client, maar enkel op aanvraag.
Opgelet: Deze scope kan enkel worden gebruikt in combinatie met client credentials grant (machine-to-machine authentication).
Indien nodig kunnen we scopes op maat voorzien. Neem hiervoor contact met ons op door te antwoorden op de e-mail die je ontvangen hebt met de gegevens van de client.
Naar welke URL initialiseer je de OAuth flow?
- Voor een user centric flow (Authorization code grant) stuur je een request naar https://…..smartschool.be/OAuth?client_id=…&redirect_uri=….&response_type=code&scope=…
- Voor een client centric flow (Client credentials grant) stuur je een request naar https://…..smartschool.be/OAuth/index/token?client_id=…&client_secret=…&scope=exerciseresults&grant_type=client_credentials
Als resultaat krijg je bijvoorbeeld: {“access_token”:”QSerH52PZ4GudbB8usSVum3KzAk1uBu3mcAbSnwK”,”token_type”:”Bearer”,”expires_in”:8640000} - Requesten verstuur je steeds naar je eigen Smartschoolplatform en niet naar oauth.smartschool.be
Hoe verloopt het versturen van API calls nadat de koppeling is gelegd voor een user centric flow (Authorization code grant)?
Indien je een access_token hebt verkregen voor een bepaalde gebruiker is het mogelijk calls te doen naar de OAuth API. Dit is een gewone http request naar https://school.smartschool.be/Api/V1/…
De parameters kan je zowel via POST of GET sturen.
- Indien je beschikt over de userinfo scope kan je een request sturen naar /Api/V1/userinfo?access_token=…
- Indien je beschikt over de fulluserinfo scope kan je een request sturen naar /Api/V1/fulluserinfo?access_token=…
- Indien je beschikt over de groupinfo scope kan je een request sturen naar /Api/V1/groupinfo?access_token=…
- Indien je beschikt over de sendmessage scope kan je een request sturen naar /Api/V1/sendmsg?access_token=…&messageTitle=….&messageBody=…
- Indien je beschikt over de sendnotif scope kan u een request sturen naar /Api/V1/sendnotif?access_token=…notifTitle=…notifDesc=…notifUrl=…
Hoe verloopt het versturen van API calls nadat de koppeling is gelegd voor een client centric flow (Client credentials grant)?
De client centric flow is enkel voor het terugsturen van resultaten naar Skore (resultservice).
Indien je een access_token hebt verkregen via de client credentials oauth flow en je beschikt over de exerciseresults scope, kan je een API request sturen naar https://….smartschool.be/Api/Resultservice/resultservice
Voor de authenticatie is een header nodig ‘Authorization’ => ‘Bearer QSerH52PZ4GudbB8usSVum3KzAk1uBu3mcAbSnwK’
De data dien je als POST te sturen in JSON-formaat. Bij deze een kort voorbeeld van de datastructuur.
Je kan meerdere evaluaties doorsturen in één request. Je kan meermaals resultaten doorsturen voor eenzelfde evaluatie en leerling, enkel het laatste resultaat zal getoond worden in het puntenboek.
Wat te controleren bij fouten tijdens het opzetten van de koppeling?
Controleer of je de juiste redirect_uri oproept. Deze moet 100% identiek zijn aan de URI die je hebt opgegeven via het aanvraagformulier. Zelfs het wijzigen van http in https vormt een verschil en de koppeling zal pas werken nadat je dit aan ons gemeld hebt.
Controleer of je de opgegeven redirect_uri “urlencoded” hebt. Deze moet er dus uitzien als bijvoorbeeld: https://school.smartschool.be/OAuth?response_type=code&client_id=123&scope=userinfo&redirect_uri=http%3A%2F%2Fwww.uwdomein.be%2Fsmartschool_authenticatie
Hoe kan de koppeling van een bestaande gebruiker verbroken worden?
Wil je in je eigen applicatie de mogelijkheid bieden om de koppeling met de Smartschoolaccount te verbreken, dan kan dat door een request te versturen naar /Api/V1/revoke?access_token=….
Hierna zal het access_token bij ons ingetrokken worden.
Sowieso kan een Smartschoolgebruiker in zijn profiel in Smartschool ook steeds de koppeling verbreken. Je toepassing zal in het profiel steeds zichtbaar zijn voor hem met vermelding van de toegestane scopes.
Hoe lang blijft een access_token geldig en kan dit worden verlengd?
Een access_token blijft slechts één uur geldig. Bij het initieel aanvragen van een access_token via de verkregen code wordt ook een refresh_token meegegeven.
Maak je een uitgebreide applicatie en wil je mogelijk na een uur nog API-requesten sturen, dan zal het nodig zijn door middel van je refresh_token je access_token te vernieuwen.
Refresh_tokens blijven momenteel 3 jaar geldig.
Access_token’s kunnen vernieuwd worden door een request te versturen om het access_token op te halen naar …/OAuth/index/token met het ‘grant_type’ = ‘refresh_token’ en het refresh_token als parameter.
Dit op gelijkaardige wijze zoals initieel het access_token wordt opgehaald door de verkregen code als parameter ‘code’ door te sturen (‘grant_type’ is hierbij ‘authorization_code’).
OAuth credentials voor uw toepassing aanvragen
Vul het formulier in om uw clientID en secretID te ontvangen voor het opzetten van de OAuth2-integratie. Nadat we uw aanvraag ontvangen hebben, nemen we contact met u op via het opgegeven e-mailadres.