Smartschool supporte OAuth2. Permettez aux utilisateurs de se connecter dans votre application avec leur compte Smartschool.
OAuth Flow
OAuth – Questions et réponses
1. 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.
2. 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.
3. À 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 que vous indiquez pour votre application dans le Questionnaire développeurs commence toujours par 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 indiqué dans le Questionnaire développeurs, y compris https:// et éventuellement le trajet de l’url (/login.php).
4. 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.
5. 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.
6. Faut-il demander un client OAuth à part par application?
Non, vous pouvez utiliser le même client pour plusieurs applications au sein de votre école ou de votre communauté scolaire. Chaque nouvelle application doit toutefois d’abord être évaluée par nos soins. Pour cela, envoyez-nous un Questionnaire développeurs mis à jour.
7. 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.
8. 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.
9. 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.
10. 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.
11. 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.
12. Que se passe-t-il après la demande du client OAuth?
Après approbation, vous recevrez un client identifier et un client secret qui vous permettent de passer à l’action. Conservez le client secret en lieu sûr et jamais dans le code source.
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
13. 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).
Exemple: Resultservice External API – resultservice-external-v1.yaml
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.
14. Vers quelle URL faut-il initialiser 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
15. Comment se déroule l’envoi des appels API une fois le lien créé 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=…
16. Comment se déroule l’envoi des appels API une fois le lien créé 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.
17. 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 indiqué dans le Questionnaire développeurs.
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=https%3A%2F%2Fwww.votredomaine.be%2Fsmartschool_authentification
18. 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.
19. 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 une intégration ou des identifiants OAuth
Vous êtes développeur ou éditeur de logiciels et souhaitez connecter votre application à Smartschool via OAuth2 ? Votre demande se déroule alors comme suit :
- Vous remplissez entièrement le formulaire de demande pour développeurs (le questionnaire) et vous le signez.
- Nous traitons les demandes complètes dans un délai raisonnable. Si nécessaire, nous vous demandons des informations techniques complémentaires, une démo, une vérification de références ou un entretien.
- Nous évaluons votre demande sur la base des critères de la Politique Développeurs et vous communiquons notre décision motivée par e-mail.
Les Conditions Développeurs s’appliquent à votre demande ainsi qu’à l’utilisation de Smartschool OAuth.
Remplissez le formulaire pour recevoir votre clientID et votre secretID afin de mettre en place l’intégration OAuth2. Dès réception de votre demande, nous vous contacterons à l’adresse e-mail indiquée.