S'authentifier sur l'API d'EtuUTT - Site étudiant de l'UTT

S'authentifier sur l'API d'EtuUTT

Afin d'utiliser l'API du site etudiant, vous devez récupérer un token qui permet d'identifier votre application ainsi l'utilisateur connecté. Il y a plusieurs façon de récuper ce token qui va dépendre du fonctionnement de votre application :

• OAuth 2.0 Authorization Code : Pour les sites web
• OAuth 2.0 Client Credentials : Pour les systèmes autonomes (borne, par exemple)
• Dynamic Client Registration : Pour les applications natives (application mobiles, par exemple)

Pour tous ces modes d'authentification, vous allez devoir demander à l'utilisateur qui se connecte l'autorisation d'accéder à ses informations personnelles. Les différentes informations de l'utilisateur sont regroupés dans des groupe qu'on appelle des scopes. Essayer de ne demander que les informations que vous allez utiliser afin de ne pas effrayer l'utilisateur :

• public : Profile publique
• private_user_account : Profil privé
• private_user_schedule : Emploi du temps
• private_user_organizations : Profil associatives

Dans la référence de l'API, vous pouvez savoir si endpoint nécéssite un scope en laissant votre souris sur le trousseau de clé à gauche de l'URI. S'il n'y a pas de trousseau, c'est que le scope est public.

Dynamic Client Registration

Si l'application que vous developpez est une application native (application modbile par exemple), ce mode d'authentification est le plus adapté, car dans votre cas, il n'est pas possible de garder une chaine secrete alors que la sécurité des deux autres méthodes reposent sur cela.

Redirection de l'utilisateur vers EtuUTT

Même si votre application n'est pas sur le web, l'utilisateur va devoir se connecter, et accepter de vous partager ses données. Comme l'utilisateur doit pouvoir rentrer ses identifiants UTT, le seul moyen pour cela est de lui afficher une page web. Pour cela, il vous suffira d'intégrer un navigateur dans votre application. Donc la première étape va être d'afficher la page web suivante à l'utilisateur afin qu'il se connecte et autorise l'accès à ses données :

https://etu.utt.fr/api/oauth/client-create?name=Your app&device=Android OnePlus 5&device_uid=ABCDEFGXYZ&scope=public private_user_account

Paramêtres :

• name : Nom de votre application
• device : Chaine de caractère décrivant l'appareil sur lequel l'application est installé. Soyez un maximum descriptif afin que l'utilisateur puisse reconnaitre sont appareil dans la page des applications qu'il a autorisé. Par exemple : Android Samsung Galaxy S42.
• device_uid : ID Unique associé à l'appareil. Essayez de donner un ID unique qui ne changera pas si l'application est reinstallé ou réinitialisé mais qui sera différent pour chaque appareil. Cela servira à supprimer les anciens ID générés dans le cas d'une réinstallation d'application afin que l'utilisateur ne se retrouve pas avec 200 applications autorisées. Si vous n'avez pas moyen d'avoir ce genre d'ID, vous pouvez en générer un à partir des informations sur l'appareil de l'utilisateur que vous pouvez hasher par exemple.
• scope : Liste des scopes auxquels vous souhaiter accéder séparés par des espaces

 Une fois sur cette page, l'utilisateur va devoir se connecter, puis accepter de vous partager ses informations.

Retour de l'utilisateur après acceptation

Lorsque l'utilisateur accepte, il est redirigé vers :

http://etuutt.invalid/?client_id=12345678901&client_secret=445dd51ef01250c8b2296eea48c7abcd

Evidement, ce site n'existe pas, donc si vous ne faites rien, l'utilisateur tombera sur une page indisponible. Le but est que vous surveillé le domaine sur lequel est actuellement le navigateur intégré à votre application. Si le domaine est etu.utt.fr, vous laissez la page se charger. Si le domaine est etuutt.invalid, alors vous fermez le navigateur et vous récupérez les parametres qui sont dans l'URI.

Dans le cas d'un succès, vous trouverez les parametres client_id et client_secret qui vont vous permettre, par la suite de récupérer un token. Vous pouvez stocker ces parametres dans l'appareil de l'utilisateur.

Retour de l'utilisateur après refus

Le refus est simillère à au succès, à la différence que les parametres sont différents :

http://etuutt.invalid/?error=authentification_canceled&error_message=L\'utilisateur a annulé l\'authentification.

Vous trouverez deux parametres :

• error : Un code d'erreur. Par exemple authentification_canceled si l'utilisateur a cliqué sur le bouton annuler.
• error_message : Un message d'erreur en français expliquant l'erreur.

Récupération du token

La récupération du token va être la même que pour le mode Client Credentials. Il faut donc que vous envoyez une requête POST à l'adresse

https://etu.utt.fr/api/oauth/token

Avec les parametres suivants :

• grant_type : client_credentials
• scope : La liste des scopes que vous aller utiliser avec ce token
• client_id : Celui que vous avez récupéré à l'étape précédente
• client_secret : Celui que vous avez récupéré à l'étape précédente

Par exemple :

POST https://etu.utt.fr/api/oauth/token

grant_type=client_credentials
client_id=12345678901
client_secret=445dd51ef01250c8b2296eea48c7abcd
scopes=public

Et vous optiendrez une réponse de la forme

{
    "access_token": "60ad5ec5f72c69ae4338e75b7458d2ab",
    "expires_at": "1506984597",
    "expires": "1506984597",
    "scopes":
    [
        "public"
    ],
    "token_type": "Bearer"
}

Renouvellement du token

Comme vous pouvez le voir, ce token a une date d'expiration (1h). Cependant pour le renouveller, il vous suffira de refaire l'étape précédente.