Receiving the Signed Request
Introduction
Every entry of a Speakap Application is loaded through a signed request. Securely handling the signed request is a critical element for implementing any Speakap Application.
Request parameters
The signed request is received by the application as a POST request to the URL provided in the manifest entry. The POST request contains the following parameters:
| Parameter | Description |
|---|---|
| appData | A freely formatted string that may be used for allowing deep-linking into the application. This parameter is never generated by Speakap, instead it is passed from alerts or updates generated by the application itself, for example. |
| issuedAt | An ISO 8601 formatted timestamp indicating when the request was signed. |
| locale | The locale to be used in RFC 5646/4647 format, e.g. en-US or nl-NL. |
| networkEID | The EID of the network from which the application was loaded. |
| role | The key of network role assigned to the logged in user. |
| signature | The signature used to prove the signed request was initiated by Speakap. |
| userEID | The EID of the network profile of the logged in user loading the application. |
The networkEID and userEID parameters provide the loaded application with the necessary context in which it is operating. The locale parameter should be used to display the application’s UI in the locale requested by the user (if the application doesn’t support the locale requested, it should default to “en-US”).
Example
An example signed-request looks a little like this:
appData=&issuedAt=2014-03-25T10%3A27%3A03.219%2B0000&locale=en-US&networkEID=08e1e1eadc000e6c&userEID=08e1e1eead0dc968&signature=8A366vpKRwnUXoYs8HRxkOQincftsX2O5ZyJ240NPdM%3DBesides validating the entire challenge against the signature, also the timestamp (issuedAt) must be validated.
Encoding
The signed request is encoded according to RFC3986 (http://www.ietf.org/rfc/rfc3986.txt).
Security
The signed request is signed so the application developer can trust the request is actually originating from Speakap and can rely on the fact the userEID actually belongs to an authenticated logged in Speakap user in the network specified by the networkEID property. To make sure the request has not been tempered with, the application developer needs to compare the passed signature to a signature it generates itself, and if the results are not the same it should reject the entire request. In addition, the application developer should check the timestamp given with the issuedAt parameter is not too old, to avoid the risk of replay attacks. We recommend allowing a window of up to 60 seconds. Setting this window too large allows for more room for replay-attacks. Setting this window too narrow may result in rejecting legitimate requests from slow connections.
The method used for generating the signatures is loosely based on oAuth 1.0a: http://oauth.net/core/1.0a/#signing_process
Some excellent documentation for this process is also provided by Twitter.
Libraries
In order to make the process easier for application developer, we also provide libraries for checking the signatures, as well as performing server-to-server API requests. These libraries can be downloaded from the Speakap-SDK GitHub repository: https://github.com/SpeakapBV/Speakap-SDK
We currently provide implementations for: Python, PHP and Node.js.