Developer Center

Authenticating Requests

Last Updated: Jun 09, 2015 09:22AM CEST

Overview

To ensure that an app knows that a request is made from Mambu and untampered, Mambu uses the App Key to sign the requests. Both Mambu and the developer's application need to have the same secret key to be able to encode and decode the requests.

All app requests coming from Mambu are submitted as a web form. These requests are encrypted using the App Key that was defined when creating the App, with the results rendered in an iframe.



When an App is loaded inside Mambu, the form submitted and posts a request to the App URL which includes a signed_request parameter. This parameter has the pattern "<PART1>.<PART2>". PART2 contains the Base64 encoded JSON map of the actual request parameters and PART1 contains an hmacSHA256 signature created using the App Key. The JSON map contains contextual parameters which explain which user opened the app in which context (e.g. under which client or loan and for which tenant, in case you're offering a multi-tenant app).

If the signature (PART1) matches the actual request (PART2), the app can be sure it was a request made from Mambu and untampered. If this is performed over HTTPS (as it always should) you'd also know that the connection was secure and information being passed across couldn't have been seen by 3rd parties. In order to check if the signature matches, you need to hash the base64 encoded PART2 using the algorithm mentioned in the decoded PART2 (currently "hmacSHA256") and your App Key. If your own generated hash and PART1 are equal, you can assure, that the request wasn't tampered.


Example

Lets take a look at how a signed_request is encoded and signed taking the example of the follow JSON map of the request parameters: Note that line breaks have been introduced below for readability and there could also be another request parameter called OBJECT_ID if the app was embedded e.g. in a Mambu client or loan view.
{
   "USER_KEY":"402832b43809601c013809601f9d0002",
   "ALGORITHM":"hmacSHA256",
   "TENANT_ID":"demo_tenant"
}

First, the Mambu server encoded this to base 64 which would result in:
eyJVU0VSX0tFWSI6IjQwMjgzMmI0MzgwOTYwMWMwMTM4MDk2MDFmOWQwMDAyIiwiQUxHT1

JJVEhNIjoiaG1hY1NIQTI1NiIsIlRFTkFOVF9JRCI6ImRlbW9fdGVuYW50In0
This string is then encrypted using the algorithm (hmacSHA256) and the App Key which was specified for the App which results in the request signature as PART1. For example, if the App Key was 'key' the signature would be:
053474bd679c9d466bd13cbda032d552966f486f34e2a24f938fd8895936bece
The two are the concatenated together to produce the final signed request in the pattern "<PART1>.<PART2>"
053474bd679c9d466bd13cbda032d552966f486f34e2a24f938fd8895936bece.

eyJVU0VSX0tFWSI6IjQwMjgzMmI0MzgwOTYwMWMwMTM4MDk2MDFmOWQwMDAyIiwiQUxHT1

JJVEhNIjoiaG1hY1NIQTI1NiIsIlRFTkFOVF9JRCI6ImRlbW9fdGVuYW50In0

This is passed in as the signed_request of the form POST to the App's endpoint URL. The application would then take this request, use the same App Key to encode the request (PART2) using hmacSHA256 and check to make sure the resulting signature matches the one in the request (PART1).

The app will then decode the base 64 encoded request (PART2) to get back to the original JSON request and perform any operations it needs to at the endpoint URL.
support@mambu.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete