This is a beta release. We are looking for feedback from our partners before finalizing the design so we know it is easy to use and covers what you need.
HMAC (Hash-based Message Authentication Code) is a method used to ensure that an order request originates from the Next system and that the data within the request has not been tampered with. Each request includes a hash value for this purpose. Additionally, the request contains information about the currently logged-in Next user, so you can create a single-sign-on (SSO) experience towards your system.
We strongly encourage you to implement HMAC for all your products to enhance security.
Enabling HMAC for Your Product
To get started, you need to enable HMAC for your product in the Partner Portal and create a shared secret. HMAC is enabled by default for new products, but we highly recommend activating HMAC verification for existing products as well.
1) Edit the product and select the HMAC option.
2) Generating an HMAC Secret on the HMAC secret. First open the product credentials page
Then generate a HMAC secret.
Be sure to store this key, and store it securely. You will need it to verify the signature of incoming requests. If you lose the key or it is exposed, you can generate a new key in the Partner Portal. It will take a few minutes for the new key to propagate to all the Next’s installations so you might want to try both the new and the old secret for period when calculating and comparing HMAC.
Steps to Validate an HMAC Signature
Example code is available here: Fiddle with example
1. Get the raw data
Begin by retrieving the raw data from the Form-encoded Post request. The fields are named orderdata and hmacsignature. The order data will be a string with json encoded data. Only plain for-decoding should be perfomed for the fields.
The following fields will be included in the json data:
hmacTimestampcurrentUserIdcurrentUserEmailcurrentUserNamecorrelationIdorderUrlinstallationIdorderIdestateIddepartmentIddepartmentOrganizationNumber
Note: The HMAC in this example will not validate and should be updated accordingly.
2 Verify the orderdata by use of the HMAC-signature.
You validate the data by hasing it yourself with the shared secret generated in the partner portal. If the two hashes are equal, you have verified that no-one has tampered the data and that they originate from Next. The HMAC algorithm needs a byte array. Convert the string to byte using UTF8, and then the HMAC SHA256 algorithm. As a result the algorithm will give you a HMAC signature. The HMAC-signature from Next is base64 encoded, so make sure you either compare encoded or decoded values.
3. Validate the Timestamp
The hmacTimestamp parameter is added for you to defend against replay attacks, where an attacker reuses a previously valid request to create multiple
fraudulent orders or cause other disruptions. It is a Unix time with millisecond precision.
To validate the timestamp:
- Ensure that it is close to the current server time.
- Allow for minor discrepancies due to differences in server clocks by accepting timestamps slightly in the future.
4. Validate any url data
If the Hmac values match and the timespan is as expected you can trust the data in the json. If not the request should be rejected. Further, you have not validated any data used in routing the request to your endpoint. If you use installationId in your Url, you need to validate it by comparing it the the one in the orderdata json.