HMAC Authentication

Data integrity checks are vital to secure a communication. Aruba Central Webhooks provides a way to validate the authenticity and integrity of the alert events data received by the user application using HMAC. Hash-based Message Authentication Code (HMAC) is a mechanism for calculating a message authentication code involving a hash function in combination with a secret key.

HMAC Algorithm

In order to use the HMAC, a message digest is computed first. Message digest is a fixed size numeric representation of the contents of a message, computed by a hash function. The following are required to compute message digest.

• Secret Key / Token of Aruba Central Webhook
• HTTP data to be authenticated (received from Aruba Central Webhook)
• headers ['X-Central-Service', 'X-Central-Delivery-ID' and 'X-Central-Delivery-Timestamp']

To validate the integrity of the received message, the computed authentication code should be same as the received HTTP message header['X-Central-Signature']. When an attacker tampers the message in between Aruba Central and end user application, the resulting hash will not match the header['X-Central-Signature'].

To validate authenticity (i.e., if the data is sent by legit source such as Aruba Central), HMAC makes use of the shared secret key / token to compute the authentication code. Thus checking if the computed signature with the header['X-Central-Signature'] validates both integrity and authenticity of the received Webhook message.

Obtaining Secret Key / Token

A secret key or token will be generated in Aruba Central upon creation of Webhooks. To obtain the secret key for a webhook,

Web UI

• Follow Account Home -> Global Settings -> Webhooks to get to the Webhook table.
• The webhook table contains the following columns: Name, Number of URL Entries, Updated At, Webhook ID, Token, Edit, Delete
• Copy the Token field from the required Webhook entry.

REST API
To obtain security key via REST API pick one of the options below.

📘

Note

The domain name for the Request URL can be obtained from the previous section Making API calls

• Get Webhook ID from list of Webhooks: List of all Webhooks are returned with this API call. The Webhook ID and the security key / token can be obtained from the list.
  API Endpoint: '/central/v1/webhooks'
  Request Method: GET
  Request Headers:
  'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
  Response Payload:

{
  "count": 1,
  "settings": [
    {
      "wid": "e26450be-4dac-435b-ac01-15d8f9667eb8",
      "name": "AAA",
      "updated_ts": 1523956927,
      "urls": [
        "https://example.org/webhook1",
        "https://example.org/webhook1"
      ],
      "secure_token": {
        "token": "KEu5ZPTi44UO4MnMiOqz",
        "ts": 1573461177
      }
    }
  ]
}

• Find from specific Webhook ID: Security token will be available in the response JSON message.
  API Endpoint: "/central/v1/webhooks/{wid}"
  Request Method: GET
  Request Headers:
  'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
  Response Payload:

{
  "wid": "e26450be-4dac-435b-ac01-15d8f9667eb8",
  "name": "AAA",
  "updated_ts": 1523956927,
  "urls": [
    "https://example.org/webhook1",
    "https://example.org/webhook1"
  ],
  "secure_token": {
    "token": "KEu5ZPTi44UO4MnMiOqz",
    "ts": 1573461177
  }
}

• Get Webhook Token: There is an API endpoint to obtain just the Security Token based on the Webhook ID.
  API Endpoint: "/central/v1/webhooks/{wid}/token"
  where 'wid' is the webhook id.
  Request Method: GET
  Request Headers:
  'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
  Response Payload:

{
  "name": "AAA",
  "secure_token": "[{\"token\": \"zSMrzuYrblgBfByy2JrM\", \"ts\": 1523957233}]"
}

Refreshing Webhook Secret Key / Token

There might be a need for the end user application to refresh the secret key / token of a Webhook for additional security. A REST API call can be made periodically to refresh the Webhook secret key based on the user's requirement.

In order to achieve that using REST API, make a PUT HTTP request to the following API endpoint.
API Endpoint: '/central/v1/webhooks/{wid}/token'
where 'wid' is the webhook id.
Request Method: PUT
Request Headers:
'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
Response Payload:

{
  "name": "AAA",
  "secure_token": "[{\"token\": \"zSMrzuYrblgBfByy2JrM\", \"ts\": 1523957233}]"
}