Empfangen der Signed Request

Einleitung

Jeder entry einer Speakap-Anwendung wird durch eine signed request geladen. Die sichere Handhabung der signed request ist ein wesentliches Element für die Inbetriebnahme jeder Speakap-Anwendung.

Anfragenparameter

Die signed request wird durch die Anwendung als eine SENDEN-Anfrage an die URL, die im Manifest entry enthalten ist, empfangen. Die SENDEN-Anfrage beinhaltet die folgenden Parameter:

Parameter Beschreibung
appData Eine frei formatierte Zeichenfolge, welche verwendet werden kann, um tiefe Verlinkungen in die Anwendung zu erlauben. Dieser Parameter wird nie durch Speakap erzeugt, stattdessen wird er von Alarmen oder Aktualisierungen übermittelt, die beispielsweise durch die Anwendung selbst erzeugt werden.
issuedAt Ein Zeitstempel im ISO 8601 Format, der erkennen lässt, wann die Anfrage getätigt wurde.
locale Die Sprachumgebung, die im RFC 5646/4647 Format, z. B. “en-US” oder “nl-NL” genutzt werden soll.
networkEID Die EID des Netzwerks, von welchem die Anwendung geladen wurde.
role Der Schlüssel der Netzwerkfunktion, der dem eingeloggten Nutzer zugeordnet wurde.
signature Die signature, um zu belegen, dass die bestätigte Anfrage von Speakap initialisiert wurde.
userEID Die EID des Netzwerkprofils des eingeloggten Nutzers, der die Anwendung lädt.

Die Parameter networkEID und userEID bieten der geladenen Anwendung den notwendigen Kontext, in welchem sie agiert. Der locale Parameter sollte genutzt werden, um die UI der Anwendung in der Sprachumgebung anzuzeigen, die vom Nutzer angefordert wurde. (Falls die Anwendung die angeforderte Sprachumgebung nicht unterstützt, sollte sie standardmäßig „en-US“ sein).

Beispiel

Ein Beispiel signed-request sieht in etwa wie folgt aus:

appData=&issuedAt=2014-03-25T10%3A27%3A03.219%2B0000&locale=en-US&networkEID=08e1e1eadc000e6c&userEID=08e1e1eead0dc968&signature=8A366vpKRwnUXoYs8HRxkOQincftsX2O5ZyJ240NPdM%3D

Neben der Bestätigung der kompletten Aufgabe gegenüber der signature muss auch der Zeitstempel (issuedAt) bestätigt werden.

Verschlüsselung

Die signed request wird übereinstimmend zu RFC3986 verschlüsselt (http://www.ietf.org/rfc/rfc3986.txt).

Sicherheit

Die signed request ist bestätigt, also kann der Anwendungsentwickler darauf vertrauen, dass die Anfrage wirklich von Speakap stammt und er kann sich auf die Tatsache verlassen, dass die userEID wirklich zu einem bestätigten, eingeloggten Speakap-Nutzer im durch das networkEID Element festgelegten Netzwerk gehört. Um sicher zu stellen, dass die Anfrage nicht verwechselt wurde, muss der Anwendungsentwickler die weitergegebene signature mit einer signature, die durch die Anfrage selbst generiert wird, vergleichen, und falls die Ergebnisse nicht die übereinstimmen, sollte er die gesamte Anfrage zurückweisen. Ergänzend sollte der Anwendungsentwickler kontrollieren, dass der mit dem issuedAt-Parameter erzeugte Zeitstempel nicht zu alt ist, um das Risiko von Wiederholungsattacken zu vermeiden. Wir empfehlen ein Zeitfenster von bis zu 60 Sekunden zu erlauben. Dieses Zeitfenster zu weit festzulegen bietet mehr Raum für Wiederholungsattacken. Dieses Zeitfenster zu eng zu setzen könnte zur Zurückweisung berechtigter Anfragen von langsamen Verbindungen führen.

Die Methode zur Generierung der signatures ist frei nach oAuth 1.0a: http://oauth.net/core/1.0a/#signing_process

Eine sehr gute Beschreibung für diesen Prozess wird bei Twitter geboten.

Bibliotheken

Um den Prozess für Anwendungsentwickler einfacher zu machen, bieten wir auch Bibliotheken zum Prüfen der signatures, genauso wie die Durchführung von Server-to-Server-API-Anfragen. Diese Bibliotheken können aus dem Speakap-SDK GitHub Speicher heruntergeladen werden: https://github.com/SpeakapBV/Speakap-SDK

Derzeit bieten wir Ausführungen für: Python, PHP und Node.js.