Come un’applicazione si connette a OpenPlatform: l’avvio e la verifica

Quando un utente apre un’applicazione, OpenPlatform non le invia una password né un cookie. Le invia un indirizzo di avvio monouso, e l’applicazione richiama OpenPlatform per sapere chi è l’utente. Questa pagina segue il codice (schemas/account.js, azione Account/run, e controllers/verify.js).

1. L’avvio

Quando l’utente fa clic su un’applicazione, il portale chiama l’API run/{appid}. OpenPlatform:

1. controlla che l’applicazione sia nell’elenco dell’utente (altrimenti App not found) e che non sia disabilitata;
2. crea una sessione dell’applicazione (tabella tbl_app_session) che scade secondo l’impostazione app_session_expire (un giorno per impostazione predefinita);
3. costruisce l’indirizzo di verifica: l’url della piattaforma + /verify/?token= + l’identificativo della sessione unito all’identificativo dell’installazione con X, seguito da X e da un checksum (FUNC.checksum, che usa il segreto saltchecksum);
4. deriva i due token di quella sessione dai segreti condivisi dell’applicazione:
   • reqtoken = l’MD5 dell’indirizzo di verifica con il sale del reqtoken dell’applicazione, in minuscolo;
   • restoken = l’MD5 di quel reqtoken con il sale del restoken dell’applicazione;

apre l’applicazione al suo url con un parametro di query in più: openplatform=<verification address>~<reqtoken>.

Per un’applicazione contrassegnata come segnalibro non c’è handshake: l’indirizzo riceve invece ssid=<session checksum>.

2. La verifica

L’applicazione prende il valore di openplatform, cioè l’indirizzo di verifica, una ~ e il reqtoken della sessione, e:

1. calcola il proprio restoken: l’MD5 del reqtoken con il sale del restoken che condivide con OpenPlatform;
2. chiama con GET l’intero valore di openplatform (la ~ e il reqtoken restano nella query string) con l’intestazione x-token impostata su quel restoken.

OpenPlatform poi (controllers/verify.js):

1. divide il token della query all’ultima ~ (la parte dopo è il reqtoken che ha inviato) e rifiuta la chiamata quando manca l’intestazione o il token;
2. controlla il checksum dell’identificativo di sessione, legge la sessione e confronta entrambi i segreti (reqtoken e il restoken dell’intestazione); qualsiasi differenza è Invalid token;
3. se l’applicazione ha un elenco di indirizzi consentiti, controlla l’indirizzo del chiamante (Not allowed IP address);
4. legge l’utente e rifiuta un utente disabilitato (User has been disabled) o inattivo (User is inactive);
5. si assicura che l’utente abbia i link di notifica di questa applicazione (tabella tbl_user_app);
6. costruisce la risposta e la fa passare dalla trasformazione verify della piattaforma, così una distribuzione può aggiungere campi.

La risposta è un oggetto JSON. I valori vuoti vengono eliminati. I suoi campi principali sono:

Campo	Cos’è
id, name, email, photo, gender, reference	chi è l’utente (photo è un indirizzo assoluto)
language, color, interface, darkmode, sounds	le preferenze (la lingua e il colore della piattaforma quando l’utente non ne ha)
sa	l’utente è amministratore della piattaforma
permissions	le stringhe value dei permessi dell’utente in questa applicazione
groups	gli id dei gruppi dell’utente
appid, ssid	l’applicazione e il checksum della sua sessione
openplatformid, openplatform	l’identificativo e l’indirizzo dell’installazione
iframe	true a meno che l’applicazione sia esterna
notify	l’indirizzo a cui inviare le notifiche, quando l’utente le accetta (notifiche)
platform	il name e il logo della piattaforma, i suoi groups e le applicazioni dell’utente

La risposta è conservata in una cache in memoria con chiave il token della sessione (la parte prima della ~) e la cache viene svuotata ogni due minuti. Una chiamata con un token presente in quella cache riceve risposta da essa, prima che i segreti vengano confrontati di nuovo; una verifica ripetuta entro quel tempo costa quindi poco.

3. Chiedere di nuovo più tardi

GET /session/ prende l’ssid che l’applicazione ha ricevuto (accetta anche openplatformid, token e session come nome del parametro), ne controlla il checksum e restituisce l’utente (id, language, name, color, sa, isonline) finché la sessione dell’utente non è scaduta.

Cosa ricordare quando costruisci l’applicazione

• Non inviare mai i segreti condivisi al browser: servono solo al server dell’applicazione.
• Verifica sul server e crea la tua sessione dalla risposta; il parametro openplatform vale per un solo avvio.
• Usa i permissions della risposta, non un ruolo inviato dal browser.
• Total.js 5 ha un client nativo per questa famiglia di protocolli: vedi OPENCLIENT.