# Wie sich eine Anwendung mit OpenPlatform verbindet: der Start und die Verifizierung

> Der genaue Handshake zwischen OpenPlatform und einer Anwendung: die Adresse, mit der sie geöffnet wird, wie die Anwendung ihre Anfrage an /verify/ signiert und die Benutzerdaten, die sie zurückbekommt.

Framework: openplatform
Product: OpenPlatform (openplatform@5)
Language: de
Content-SHA256: ecb50e6be445a5e4dc4fb3c847459e4b479c08bad600b25756bc4d7d36bf9fbe
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Wenn ein Benutzer eine Anwendung öffnet, sendet OpenPlatform ihr weder ein Passwort noch ein Cookie. Es sendet eine **einmalige Startadresse**, und die Anwendung ruft OpenPlatform zurück, um zu erfahren, wer der Benutzer ist. Diese Seite folgt dem Code (`schemas/account.js`, Aktion `Account/run`, und `controllers/verify.js`).

## 1. Der Start

Wenn der Benutzer auf eine Anwendung klickt, ruft das Portal die API `run/{appid}` auf. OpenPlatform:

1. prüft, dass die Anwendung in der Liste des Benutzers steht (sonst `App not found`) und nicht deaktiviert ist;
2. erstellt eine Sitzung der Anwendung (Tabelle `tbl_app_session`), die nach der Einstellung `app_session_expire` abläuft (standardmäßig ein Tag);
3. baut die **Verifizierungsadresse**: die `url` der Plattform + `/verify/?token=` + die Kennung der Sitzung, mit `X` verbunden mit der Kennung der Installation, gefolgt von `X` und einer Prüfsumme (`FUNC.checksum`, die das Geheimnis `saltchecksum` verwendet);
4. leitet die beiden Tokens dieser Sitzung aus den gemeinsamen Geheimnissen der Anwendung ab:
   - `reqtoken` = der MD5 der Verifizierungsadresse mit dem `reqtoken` der Anwendung als Salt, in Kleinbuchstaben;
   - `restoken` = der MD5 dieses `reqtoken` mit dem `restoken` der Anwendung als Salt;
5. öffnet die Anwendung unter ihrer `url` mit einem zusätzlichen Query-Parameter: `openplatform=<verification address>~<reqtoken>`.

Bei einer als Lesezeichen markierten Anwendung gibt es keinen Handshake: Die Adresse erhält stattdessen `ssid=<session checksum>`.

## 2. Die Verifizierung

Die Anwendung nimmt den Wert von `openplatform`, also die Verifizierungsadresse, ein `~` und das `reqtoken` der Sitzung, und:

1. berechnet **ihr eigenes** `restoken`: den MD5 des `reqtoken` mit dem `restoken`, das sie mit OpenPlatform teilt, als Salt;
2. ruft `GET` auf den gesamten Wert von `openplatform` auf (das `~` und das `reqtoken` bleiben in der Query-String) mit dem Header `x-token`, der auf dieses `restoken` gesetzt ist.

OpenPlatform dann (`controllers/verify.js`):

1. teilt das Query-Token am letzten `~` (der Teil danach ist das `reqtoken`, das es gesendet hat) und weist den Aufruf ab, wenn Header oder Token fehlen;
2. prüft die Prüfsumme der Sitzungskennung, liest die Sitzung und vergleicht beide Geheimnisse (`reqtoken` und das `restoken` des Headers); jede Abweichung ist `Invalid token`;
3. hat die Anwendung eine Liste erlaubter Adressen, prüft es die Adresse des Aufrufers (`Not allowed IP address`);
4. liest den Benutzer und weist einen deaktivierten (`User has been disabled`) oder inaktiven (`User is inactive`) Benutzer ab;
5. stellt sicher, dass der Benutzer die Benachrichtigungslinks dieser Anwendung hat (Tabelle `tbl_user_app`);
6. baut die Antwort und schickt sie durch die Transformation `verify` der Plattform, sodass eine Bereitstellung Felder hinzufügen kann.

Die Antwort ist ein JSON-Objekt. Leere Werte werden darin weggelassen. Ihre wichtigsten Felder sind:

| Feld | Was es ist |
|---|---|
| `id`, `name`, `email`, `photo`, `gender`, `reference` | wer der Benutzer ist (`photo` ist eine absolute Adresse) |
| `language`, `color`, `interface`, `darkmode`, `sounds` | die Einstellungen (Sprache und Farbe der Plattform, wenn der Benutzer keine hat) |
| `sa` | der Benutzer ist Administrator der Plattform |
| `permissions` | die `value`-Zeichenketten der Berechtigungen des Benutzers in dieser Anwendung |
| `groups` | die Ids der Gruppen des Benutzers |
| `appid`, `ssid` | die Anwendung und die Prüfsumme ihrer Sitzung |
| `openplatformid`, `openplatform` | die Kennung und die Adresse der Installation |
| `iframe` | `true`, außer die Anwendung ist extern |
| `notify` | die Adresse, an die Benachrichtigungen gesendet werden, wenn der Benutzer sie akzeptiert ([Benachrichtigungen](/en/openplatform/notifications-and-public-api/)) |
| `platform` | der `name` und das `logo` der Plattform, ihre `groups` und die Anwendungen des Benutzers |

Die Antwort wird in einem Speicher-Cache gehalten, der nach dem Token der Sitzung (dem Teil vor dem `~`) indiziert ist, und der Cache wird alle zwei Minuten geleert. Ein Aufruf mit einem Token, das in diesem Cache liegt, wird daraus beantwortet, bevor die Geheimnisse erneut verglichen werden; eine wiederholte Verifizierung in dieser Zeit ist also billig.

## 3. Später erneut nachfragen

`GET /session/` nimmt das `ssid`, das die Anwendung erhalten hat (es akzeptiert auch `openplatformid`, `token` und `session` als Parametername), prüft dessen Prüfsumme und gibt den Benutzer zurück (`id`, `language`, `name`, `color`, `sa`, `isonline`), solange die Sitzung des Benutzers nicht abgelaufen ist.

## Was Sie beim Bauen der Anwendung beachten sollten

- Liefern Sie die gemeinsamen Geheimnisse niemals an den Browser aus: Nur der Server der Anwendung braucht sie.
- Verifizieren Sie auf dem **Server** und erzeugen Sie aus der Antwort Ihre eigene Sitzung; der Parameter `openplatform` gilt für einen Start.
- Verwenden Sie die `permissions` der Antwort, nicht eine Rolle, die der Browser sendet.
- Total.js 5 hat einen nativen Client für diese Protokollfamilie: siehe [OPENCLIENT](/en/total5/openclient-protocol/).