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

> De exacte handdruk tussen OpenPlatform en een toepassing: het adres waarmee ze wordt geopend, hoe de toepassing haar verzoek aan /verify/ ondertekent en de gebruikersgegevens die ze terugkrijgt.

Framework: openplatform
Product: OpenPlatform (openplatform@5)
Language: nl
Content-SHA256: 2a2c6148404615450610679b737b85d8564e97a672b4c88b804aa9887ab0fe22
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

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;
5. 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](/en/openplatform/notifications-and-public-api/)) |
| `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](/en/total5/openclient-protocol/).