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

> L’handshake esatto tra OpenPlatform e un’applicazione: l’indirizzo con cui viene aperta, come l’applicazione firma la sua richiesta a /verify/ e i dati dell’utente che riceve.

Framework: openplatform
Product: OpenPlatform (openplatform@5)
Language: it
Content-SHA256: 6d9d0db8eb76f976aa75d786e55ffbbbb49de05d3117d9045772619b41594742
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

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