Hoe een toepassing verbinding maakt met OpenPlatform: de start en de verificatie

Wanneer een gebruiker een toepassing opent, stuurt OpenPlatform er geen wachtwoord of cookie naartoe. Het stuurt een eenmalig startadres, en de toepassing belt OpenPlatform terug om te weten wie de gebruiker is. Deze pagina volgt de code (schemas/account.js, actie Account/run en controllers/verify.js).

1. De start

Wanneer de gebruiker op een toepassing klikt, roept het portaal de API run/{appid} aan. OpenPlatform:

1. controleert dat de toepassing in de lijst van de gebruiker staat (anders App not found) en dat ze niet is uitgeschakeld;
2. maakt een sessie van de toepassing aan (tabel tbl_app_session) die verloopt volgens de instelling app_session_expire (standaard een dag);
3. bouwt het verificatieadres: de url van het platform + /verify/?token= + de identificatie van de sessie, met X verbonden met de identificatie van de installatie, gevolgd door X en een controlesom (FUNC.checksum, die het geheim saltchecksum gebruikt);
4. leidt de twee tokens van die sessie af uit de gedeelde geheimen van de toepassing:
   • reqtoken = de MD5 van het verificatieadres met de reqtoken van de toepassing als salt, in kleine letters;
   • restoken = de MD5 van die reqtoken met de restoken van de toepassing als salt;

opent de toepassing op haar url met één extra queryparameter: openplatform=<verification address>~<reqtoken>.

Voor een toepassing die als bladwijzer is gemarkeerd is er geen handdruk: het adres krijgt in plaats daarvan ssid=<session checksum>.

2. De verificatie

De toepassing neemt de waarde van openplatform, het verificatieadres, een ~ en de reqtoken van de sessie, en:

1. berekent haar eigen restoken: de MD5 van de reqtoken met de restoken die ze met OpenPlatform deelt als salt;
2. roept met GET de hele waarde van openplatform aan (de ~ en de reqtoken blijven in de query string) met de header x-token ingesteld op die restoken.

OpenPlatform dan (controllers/verify.js):

1. splitst het querytoken bij de laatste ~ (het deel erna is de reqtoken die het stuurde) en weigert de aanroep wanneer de header of het token ontbreekt;
2. controleert de controlesom van de sessie-identificatie, leest de sessie en vergelijkt beide geheimen (reqtoken en de restoken van de header); elk verschil is Invalid token;
3. als de toepassing een lijst met toegestane adressen heeft, controleert het het adres van de aanroeper (Not allowed IP address);
4. leest de gebruiker en weigert een uitgeschakelde (User has been disabled) of inactieve (User is inactive) gebruiker;
5. zorgt ervoor dat de gebruiker de meldingslinks van deze toepassing heeft (tabel tbl_user_app);
6. bouwt het antwoord en laat het door de transformatie verify van het platform lopen, zodat een implementatie velden kan toevoegen.

Het antwoord is een JSON-object. Lege waarden worden eruit weggelaten. De belangrijkste velden zijn:

Veld	Wat het is
id, name, email, photo, gender, reference	wie de gebruiker is (photo is een absoluut adres)
language, color, interface, darkmode, sounds	de voorkeuren (de taal en kleur van het platform wanneer de gebruiker er geen heeft)
sa	de gebruiker is beheerder van het platform
permissions	de value-tekenreeksen van de rechten van de gebruiker in deze toepassing
groups	de id’s van de groepen van de gebruiker
appid, ssid	de toepassing en de controlesom van haar sessie
openplatformid, openplatform	de identificatie en het adres van de installatie
iframe	true tenzij de toepassing extern is
notify	het adres om meldingen naartoe te sturen, wanneer de gebruiker ze accepteert (meldingen)
platform	de name en het logo van het platform, zijn groups en de toepassingen van de gebruiker

Het antwoord wordt bewaard in een cache in het geheugen met als sleutel het token van de sessie (het deel vóór de ~) en de cache wordt elke twee minuten gewist. Een aanroep met een token dat in die cache zit, wordt daaruit beantwoord, voordat de geheimen opnieuw worden vergeleken; een herhaalde verificatie binnen die tijd is dus goedkoop.

3. Later opnieuw vragen

GET /session/ neemt de ssid die de toepassing ontving (het accepteert ook openplatformid, token en session als naam van de parameter), controleert de controlesom en geeft de gebruiker terug (id, language, name, color, sa, isonline) zolang de sessie van de gebruiker niet is verlopen.

Wat je moet onthouden bij het bouwen van de toepassing

• Lever de gedeelde geheimen nooit aan de browser: alleen de server van de toepassing heeft ze nodig.
• Verifieer op de server en maak je eigen sessie uit het antwoord; de parameter openplatform is voor één start.
• Gebruik de permissions van het antwoord, niet een rol die de browser stuurt.
• Total.js 5 heeft een native client voor deze familie van protocollen: zie OPENCLIENT.