Smartschool OAuth
Smartschool supporte OAuth2. Permettez aux utilisateurs de se connecter dans votre application avec leur compte Smartschool.
OAuth Flow
OAuth – Questions et réponses
Qu’est-ce que OAuth2 pour Smartschool implique?
Smartschool supporte OAuth2 en tant qu’Identity provider (fournisseur d’identité), ce qui permet de créer un lien avec un utilisateur Smartschool. Une fois la connexion établie, des données peuvent être échangées et des actions peuvent être effectuées pour cet utilisateur Smartschool.
OAuth, peut-il être utilisé comme authentification unique (single sign-on)?
Oui, il est possible de permettre aux utilisateurs de se connecter à votre application web via leur compte Smartschool. Consultez l’exemple d’une application web en PHP.
À quoi sert le Redirect URI?
C’est le lien web vers lequel l’utilisateur est envoyé après sa connexion à Smartschool. Il s’agit donc de la page d’accueil de votre application qui doit être prévue dans le traitement OAuth. Ce URI doit être public.
Le redirect URI de votre application doit commencer par http ou https. Remplissez toujours le trajet complet (au lieu de mettre uniquement le nom de domaine). Par exemple : https://application.ecole.be/login.php
Le redirect URI que vous introduisez via redirect_uri=… dans le flow OAuth doit correspondre EXACTEMENT au redirect_uri rempli dans le formulaire de demande, y compris https:// ou https:// et éventuellement le trajet de l’url (/login.php).
Est-il possible d’introduire plusieurs Redirect URI pour un même client?
Si nécessaire, vous pouvez introduire plusieurs Redirect URI. Cela peut être pratique quand vous utilisez le même client pour un environnement de développement, d’acceptation et de production. Nous vous conseillons de travailler de cette manière.
Considérez également l’emploi du paramètre ‘state’ pour diriger les utilisateurs vers un endroit particulier de votre application.
Est-il possible d’attribuer plus de paramètres dans le flow OAuth?
Vous pouvez utiliser le paramètre ‘state’ facultatif lors de l’initialisation du flow OAuth.
Vous recevrez ce paramètre en retour après qu’un utilisateur ait parcouru le flow OAuth. En incluant une certaine valeur dans ce paramètre, vous pouvez éventuellement prévoir un traitement spécifique dans votre implémentation.
Ce paramètre est donc entre autres approprié pour diriger les utilisateurs vers un endroit spécifique dans votre application.
Faut-il demander un client OAuth à part par application?
Non, vous pouvez utiliser sans problème le même client pour plusieurs applications au sein de votre école ou de votre communauté scolaire.
Faut-il demander un client OAuth à part par plateforme Smartschool?
Non, nous pouvons paramétrer par client pour quelles plateformes il est d’application. Quelques options:
- Client ABC peut connecter vers la plateforme Smartschool X
- Client DEF peut connecter vers les plateformes Smartschool X, Y et Z.
- Client GHI peut connecter vers toutes les plateformes Smartschool.
Cette dernière option n’est utile que pour les intégrateurs qui offrent des services à un grand nombre d’écoles comme les maisons d’édition éducatives.
Pour des raisons de sécurité, nous conseillons au client de limiter la connexion à la ‘largeur’ nécessaire.
Quelle est la différence entre un lien vers une ou vers plusieurs plateformes?
Si vous souhaitez créer un lien vers une plateforme en particulier, il vaut mieux envoyer tous les appels OAuth et API vers la même plateforme.
- Tous les appels OAuth devront être faits vers https://ecole.smartschool.be/OAuth
- Tous les appels API devront être faits vers https://ecole.smartschool.be/Api/V1/…
Si vous souhaitez créer un lien vers plusieurs plateformes, vous pouvez diriger tous les appels vers la plateforme centrale oauth.smartschool.be.
- Tous les appels OAuth devront être faits vers https://oauth.smartschool.be/OAuth
- Tous les appels API devront être faits vers https://oauth.smartschool.be/Api/V1/…
Le flux de ce flow est comparable à celui d’un lien avec une seule plateforme, mais l’utilisateur devra introduire d’abord l’adresse URL de sa plateforme.
Si vous créez un lien vers plusieurs plateformes et vous connaissez la plateforme de l’utilisateur, vous pouvez initialiser directement le flow OAuth vers cette plateforme.
Pourquoi faut-il donner une image de l’application?
Nous vous conseillons de nous fournir un logo de votre application ou de votre organisation pour que nous puissions la montrer sur la page de connexion. Les utilisateurs seront plus confiants quand ils reconnaissent votre logo. Spécifications de l’image: 156x156px sans angles arrondis au format PNG et sans transparence.
OAuth supporte-t-il la double authentification?
Oui, un utilisateur qui a activé la double authentification sera demandée de l’appliquer lors de la connexion.
Si vous voulez utiliser OAuth pour la connexion au réseau Wi-Fi, vous pouvez nous demander de ne pas imposer cette double sécurisation. N’utilisez qu’un tel client OAuth que pour le Wi-Fi et jamais pour d’autres applications.
Qu’en est-il de l’OAuth pour des plateformes Smartschool associées à Google Apps ou Office365?
Des utilisateurs qui se connectent avec leur compte Google Apps ou Office 356 peuvent le faire également dans le flow OAuth. Cela ne pose aucun problème.
Que se passe-t-il après la demande du client OAuth?
Après avoir envoyé votre demande OAuth, vous recevrez un client identifier et un client secret qui vous permettent de passer à l’action.
Nous vous conseillons d’utiliser éventuellement un client OAuth2 disponible dans le langage de programmation que vous utilisez. Plus d’informations sur les clients sont disponibles sous ‘Client Libraries’ sur https://oauth.net/code
Quels sont les scopes disponibles?
Actuellement, plusieurs scopes sont déjà disponibles et prêt à l’emploi au sein du lien OAuth2.
Si vous souhaitez demander l’autorisation pour plusieurs scopes auprès de l’utilisateur, ceux-ci doivent être envoyés dans le flow Oauth et séparés d’une espace.
Exemple: “/OAuth?client_id=[client_id]&redirect_uri=[redirect_uri]&response_type=code&scope=[scope1 scope2 scope3]”
Scopes disponibles:
- userinfo: Demander certaines données du profil (cross-platform identifier, url de la plateforme, nom et identifiant)
Exemple: response élève/enseignant
Exemple: response compte secondaire (parents) - fulluserinfo: Demander des données du profil (par exemple: cross-platform identifier, url de la plateforme, prénom, nom, identifiant, adresse e-mail, numéro de téléphone, sexe, date de naissance)
Exemple: response compte secondaire (parents) - groupinfo: Demander l’appartenance aux groupes et aux classes
Exemple: response élève - sendmessage: Envoyer des messages (l’application peut envoyer des messages)
Ce scope n’est pas autorisé par défaut pour un nouveau client OAuth, il est disponible sur demande. - sendnotif: Envoyer des notifications (l’application peut envoyer des notifications)
Ce scope n’est pas autorisé par défaut pour un nouveau client OAuth, il est disponible sur demande.
Exemple: sendmsg et sendnotif calls - Exerciseresults: Envoyer des évaluations et résultats vers le carnet de cotes.
Ce scope n’est pas autorisé par défaut pour un nouveau client OAuth, mais uniquement sur demande.
Attention: Ce scope peut être utilisé uniquement en combinaison avec client credentials grant (machine-to-machine authentication).
Si nécessaire, nous pouvons offrir des scopes sur mesure. Contactez-nous via la réponse à l’e-mail que vous avez reçu avec les données du client.
Vers quelle URL faut-il intialiser le flux OAuth?
- Pour un centric flow (Authorization code grant) vous envoyez votre requête vers https://…..smartschool.be/OAuth?client_id=…&redirect_uri=….&response_type=code&scope=…
- Pour un client centric flow (Client credentials grant) vous envoyez votre requête vers https://…..smartschool.be/OAuth/index/token?client_id=…&client_secret=…&scope=exerciseresults&grant_type=client_credentials
Comme résultat, vous recevez p.ex: {« access_token »: »QSerH52PZ4GudbB8usSVum3KzAk1uBu3mcAbSnwK », »token_type »: »Bearer », »expires_in »:8640000} - Envoyez vos requêtes à votre propre plateforme Smartschool et pas à oauth.smartschool.be
Comment se déroule l’envour des appels API une fois le lien crée pour un user centric flow (Authorization code grant)?
Si vous avez reçu un access_token (jeton d’accès) pour un utilisateur, il est possible de faire des appels vers l’API OAuth. Il s’agit d’une requête http vers https://ecole.smartschool.be/Api/V1/…
Ces paramètres peuvent être envoyés via POST ou via GET.
- Si vous disposez du scope userinfo, vous pouvez envoyer une requête vers /Api/V1/userinfo?access_token=…
- Si vous disposez du scope fulluserinfo, vous pouvez envoyer une requête vers /Api/V1/fulluserinfo?access_token=…
- Si vous disposez du scope groupinfo, vous pouvez envoyer une requête vers /Api/V1/groupinfo?access_token=…
- Si vous disposez du scope sendmessage, vous pouvez envoyer une requête vers /Api/V1/sendmsg?access_token=…&messageTitle=…&messageBody=…
- Si vous disposez du scope sendnotif, vous pouvez envoyer une requête vers /Api/V1/sendnotif?access_token=…notifTitle=…notifDesc=…notifUrl=…
Comment se déroule l’envour des appels API une fois le lien crée pour un client centric flow (Client credentials grant)?
Le client centric flow sert uniquement pour le renvour de résultats vers Skore (resultservice).
Si vous avez reçu un access_token via le client credentials oauth flow et vous disposez du scopre exerciseresults, vous pouvez envoyer une requête API vers https://….smartschool.be/Api/Resultservice/resultservice
Pour cette authentification, il vous faut un header ‘Authorization’ => ‘Bearer QSerH52PZ4GudbB8usSVum3KzAk1uBu3mcAbSnwK’
Ces données doivent être envoyées en tant que POST au format JSON. Voici un bref exemple d’une structure de données.
Vous pouvez envoyer plusieurs évaluations dans une requête. Vous pouvez envoyer plusieurs fois des résultats pour une même évlauation et élève, seul le dernier résultat sera affiché dans le carnet de cotes.
Que peut-on vérifier en cas d’erreur lors de la création du lien?
Vérifiez si vous demandez le redirect_uri correct. Celui-ci doit correspondre exactement à celui communiqué via le formulaire de demande. Même une modification de http en https fait une différence et cela ne fonctionnera qu’après l’avoir signalé à nous.
Vérifiez si le redirect_uri communiqué à nous a été ‘urlencodé’. Celui-ci doit donc ressembler à: https://ecole.smartschool.be/OAuth?response_type=code&client_id=123&scope=userinfo&redirect_uri=http%3A%2F%2Fwww.votredomaine.be%2Fsmartschool_authentification
Comment un utilisateur peut-il annuler la connexion?
Souhaitez-vous permettre aux utilisateurs d’annuler le lien avec leur compte Smartschool dans votre application? Cela est possible en envoyant une requête vers /Api/V1/revoke ?access_token=….
Après, le access_token (jeton d’accès) sera retiré chez nous.
Un utilisateur Smartschool pourra toujours annuler les connexion. Dans son profil, un utilisateur pourra toujours voir votre application et les scopes autorisés.
Quelle est la durée de vie d’un access_token (jeton d’accès) et peut-elle être prolongée?
Un access_token (jeton d’accès) n’est valable que pendant une heure. Lors de la demande initiale d’un access_token depuis le code reçu, un refresh_token est également attribué.
Si vous faites une application étendue et vous souhaitez éventuellement envoyer des requêtes API après une heure, il sera nécessaire de renouveler votre access-token à l’aide d’un refresh_token.
Les refresh_tokens sont actuellement valables pendant trois ans.
Les access_tokens peuvent être renouvelés en envoyant une requête pour obtenir l’access_token vers …/OAuth/index/token avec le ‘grant_type’ = ‘refresh_token’ et le refresh_token comme paramètre.
Cette méthode correspond à celle utilisée pour obtenir initialement l’access_token en envoyant le code reçu comme paramètre ‘code’ (‘grant_type’ est alors ‘authorization_code’).
Demander des credentials OAuth pour votre application
Remplissez le formulaire pour recevoir votre clientID et secretID pour créer l’intégration OAuth2. Après avoir reçu votre demande, nous vous contacterons via l’adresse e-mail remplie dans le formulaire.