About HMAC authentication

HMAC

🚧

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=="'}