Comment une application se connecte à OpenPlatform : le lancement et la vérification

Quand un utilisateur ouvre une application, OpenPlatform ne lui envoie ni mot de passe ni cookie. Il lui envoie une adresse de lancement à usage unique, et l’application rappelle OpenPlatform pour savoir qui est l’utilisateur. Cette page suit le code (schemas/account.js, action Account/run, et controllers/verify.js).

1. Le lancement

Quand l’utilisateur clique sur une application, le portail appelle l’API run/{appid}. OpenPlatform :

1. vérifie que l’application figure dans la liste de l’utilisateur (sinon App not found) et qu’elle n’est pas désactivée ;
2. crée une session de l’application (table tbl_app_session) qui expire selon le réglage app_session_expire (un jour par défaut) ;
3. construit l’adresse de vérification : l’url de la plateforme + /verify/?token= + l’identifiant de la session joint à l’identifiant de l’installation par X, suivi de X et d’une somme de contrôle (FUNC.checksum, qui utilise le secret saltchecksum) ;
4. dérive les deux jetons de cette session à partir des secrets partagés de l’application :
   • reqtoken = le MD5 de l’adresse de vérification salée avec le reqtoken de l’application, en minuscules ;
   • restoken = le MD5 de ce reqtoken salé avec le restoken de l’application ;

ouvre l’application à son url avec un paramètre de requête supplémentaire : openplatform=<verification address>~<reqtoken>.

Pour une application marquée comme signet, il n’y a pas d’échange : l’adresse reçoit ssid=<session checksum> à la place.

2. La vérification

L’application prend la valeur de openplatform, qui est l’adresse de vérification, un ~ et le reqtoken de la session, et :

1. calcule son propre restoken : le MD5 du reqtoken salé avec le restoken qu’elle partage avec OpenPlatform ;
2. appelle en GET la valeur entière de openplatform (le ~ et le reqtoken restent dans la query string) avec l’en-tête x-token fixé à ce restoken.

OpenPlatform ensuite (controllers/verify.js) :

1. découpe le jeton de la requête au dernier ~ (la partie qui suit est le reqtoken qu’il a envoyé) et refuse l’appel quand l’en-tête ou le jeton manque ;
2. vérifie la somme de contrôle de l’identifiant de session, lit la session et compare les deux secrets (reqtoken et le restoken de l’en-tête) ; toute différence donne Invalid token ;
3. si l’application a une liste d’adresses autorisées, vérifie l’adresse de l’appelant (Not allowed IP address) ;
4. lit l’utilisateur et refuse un utilisateur désactivé (User has been disabled) ou inactif (User is inactive) ;
5. s’assure que l’utilisateur a les liens de notification de cette application (table tbl_user_app) ;
6. construit la réponse et la fait passer par la transformation verify de la plateforme, de sorte qu’un déploiement puisse ajouter des champs.

La réponse est un objet JSON. Les valeurs vides en sont retirées. Ses principaux champs sont :

Champ	Ce que c’est
id, name, email, photo, gender, reference	qui est l’utilisateur (photo est une adresse absolue)
language, color, interface, darkmode, sounds	les préférences (la langue et la couleur de la plateforme quand l’utilisateur n’en a pas)
sa	l’utilisateur est administrateur de la plateforme
permissions	les chaînes value des permissions de l’utilisateur dans cette application
groups	les ids des groupes de l’utilisateur
appid, ssid	l’application et la somme de contrôle de sa session
openplatformid, openplatform	l’identifiant et l’adresse de l’installation
iframe	true sauf si l’application est externe
notify	l’adresse où envoyer les notifications, quand l’utilisateur les accepte (notifications)
platform	le name et le logo de la plateforme, ses groups et les applications de l’utilisateur

La réponse est conservée dans un cache en mémoire indexé par le jeton de la session (la partie avant le ~) et le cache est vidé toutes les deux minutes. Un appel avec un jeton présent dans ce cache reçoit sa réponse depuis lui, avant que les secrets soient comparés à nouveau ; une vérification répétée dans ce délai est donc peu coûteuse.

3. Redemander plus tard

GET /session/ prend le ssid que l’application a reçu (elle accepte aussi openplatformid, token et session comme nom du paramètre), vérifie sa somme de contrôle et renvoie l’utilisateur (id, language, name, color, sa, isonline) tant que la session de l’utilisateur n’a pas expiré.

Ce qu’il faut retenir en construisant l’application

• N’envoyez jamais les secrets partagés au navigateur : seul le serveur de l’application en a besoin.
• Vérifiez sur le serveur et créez votre propre session à partir de la réponse ; le paramètre openplatform sert pour un seul lancement.
• Utilisez les permissions de la réponse, pas un rôle envoyé par le navigateur.
• Total.js 5 possède un client natif pour cette famille de protocoles : voir OPENCLIENT.