Integrations & HMAC Authentication

[choicedraught]

Hi There,

Firstly, I absolutely ❤️ Semaphore. I’ve been using it for a couple of years now and the recent additions of the Integration API and OAuth are a huge help. Thank you 🙏 One quick bit of help if anyone has experience with this?

I am working on using an Integration to trigger a Template to run and I want to use HMAC Authentication. Is there any guidance about the HTTP request format for this to allow me to calculate the HMAC signature correctly?

In my case, I don’t need to send anything in the request body to the Integration, I simply want to have the HTTP request trigger the template to run. So if there is no request body, what do I use as the input string for the HMAC signature calculation?

I have deduced that the algorithm should be sha256 and I have configured the Integration the expect the signature in the “authsig” header.

-H “authsig: sha256=xxxxxxxxxxxxxxxxxxxxxx"

I’m assuming that the Content Type should be application/json even though there is no body.

I’m also assuming I should make a POST request.

If examples of what I’ve done so would be useful, I’ll add some.

Thanks,

Jack 🙏

[choicedraught]

Ok I got there in the end. 2 things I was doing wrong:

1. When you create an Integration you need to create a Matcher so that your Integration can be matched to the Task / Template you want to run. So in my case, I just made the body:

{"x-match-task":"task-name"}

and then setup the Matcher on my Integration to match.

2. More importantly, I was assuming that, like the GitHub Webhook, your HMAC header variable needed to be prefixed with sha256= however this is not the case for a straight HMAC Integration. It requires no prefix and looks like this:

{"Authentication-Header":"hmac-siganture"}

where Authentication-Header is what you configured in the "Auth header" section of your Integration and hmac-signature is the computed hmac signature based on the payload and secret key.

To make a call to the Integrations API using nodejs, use something like:

/* Hacked together using examples from Stack Overflow 👍  */

const axios = require('axios');
const crypto = require('crypto');

// Set method and path for the request
let method = 'POST';
let path = '/api/integrations/xxxxxxxxxx';
let body = {"x-match-task":"my-task"};
let secret = 'MySecretKey';

const hash = crypto.createHmac('sha256', secret).update(JSON.stringify(body)).digest('hex');

const options = {
  method: method,
  url: 'https://semui.com' + path,
  headers: {
    'Content-Type': 'application/json',
    'authsig': hash
  },
  data: JSON.stringify(body)
}

// Initiate request
axios(options)
  .then(function (response) {
    console.log("Success: " + response.status);
  })
  .catch(function (error) {
    if (error.response) {
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx
      console.log(error.response.data);
      console.log(error.response.status);
      console.log(error.response.headers);
    } else if (error.request) {
      // The request was made but no response was received
      console.log(error.request);
    } else {
      // Something happened in setting up the request that triggered an Error
      console.log('Error', error.message);
    }
  });

I will add a curl example once I have one that works :)

[choicedraught]

Aaaand here is the bash / curl example. YMMV with regarding to bash quoting and variables.. eg https://stackoverflow.com/questions/17029902/using-curl-post-with-variables-defined-in-bash-script-functions

#!/bin/bash

secret="MySecretKey"
url="https://semui.com/api/integrations/xxxxxxxxxxxx"
body='{"x-match-task":"my-task"}'
authsig=`printf %s $body | openssl sha256 -hex -mac HMAC -macopt key:$secret | cut -d' ' -f2`
curl --data "$body" --header "Content-Type: application/json" $url --header "authsig: $authsig"

[choicedraught]

For extra internet points, here is the nodejs express server code I used for debugging in case it is helpful to someone :)

var express = require("express");
var crypto = require("crypto");
var app = express();
var bodyParser = require('body-parser')//add this


app.use(bodyParser());

app.use((req, res) => {
  
  console.log("Request headers: ");
  console.log(JSON.stringify(req.headers));
  console.log("");
  console.log("Request body: ");
  console.log(JSON.stringify(req.body));
  
  const secret = 'MySecretKey';
  const hash = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');

  res.json([{"Received signature":req.headers['authsig'],"Computed signature":hash}]);
  res.status(200).send();

});

app.listen(3000, () => {
 console.log("Server running on port 3000");
});

[fiftin]

It can be a tutorial ;) If you want I can add post to the blog on the website with link to your profile ;)

[choicedraught]

Oh wow, yeh that would be amazing :). Thank you!!