About HMAC authentication



Be Aware!

  • curly braces represent variables, do not include curly braces verbatim

HMAC - hash-based message authentication code

HMAC is computed as follows:
HTTP 'Authorization' header value is set to: 'HMAC {hmac_string}'

  • {hmac_string} is: 'client_id="{client_id}",ts="{ts}",nonce="{nonce}",signature="{signature}"'
    • client_id is your ZealiD Client ID
    • ts is UNIX timestamp (integer), for replay and other attack vector mitigation
      must be accurate and generated at the time the request is made
      see Wiki
    • nonce is a random string to prevent replay attacks
      64 characters are recommended, and base64 encoding can for example be used
    • signature is the HMAC signature, computed using SHA512 and base64 encoded
      Signature is computed on the following string (let's call it auth_string)
      auth_string: '{client_id}{nonce}{ts}{request_string}{payload}'
      • client_id, nonce and ts are as described above
      • request_string is '{request_method} {full_path}'
        • request_method is the HTTP request method in capitals, e.g. GET, POST, etc.
        • full_path is HTTP path with base URL excluded, e.g. '/mediator/api/get_token'; if there are any query parameters, they must be included in full, and must exactly match the URL you are requesting the resource with, exactly; e.g. '/mediator/api/something?param=1'
        • example of request_string: 'GET /mediator/api/get_token'
      • payload is the body of your POST request, if any; this is empty string if no body is sent
    • HMAC signature is then computed as:
      BASE64(HMAC-SHA512(client_secret, auth_string))


Sample header with HMAC

'Authorization': 'HMAC client_id="someclient",ts="1616494592",nonce="G9aGfYcjqMtxUIxbsQAcEHQlaba7cFBrZjknC74qEjA",signature="mx1NJbC0Erj4a+Ojiscf4gxzdDARIm9lEofn3D6I7YswQPCSQY9dx8nspek14ZJuLTlW6IyaH7oSYbIweFzS6A=="'}