HMAC Authentication

Data integrity checks are vital to secure a communication. HPE Aruba Networking 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 HPE Aruba Networking Central Webhook
• HTTP data to be authenticated (received from HPE Aruba Networking 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 HPE Aruba Networking 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 HPE Aruba Networking 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 HPE Aruba Networking 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/token via REST API pick one of the options below.

1. 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
   API Method: GET
   Base URL: https://apigw-prod2.central.arubanetworks.com
   (Replace the Base URL with correct API Gateway)
   Request Header: 'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
   Sample Response Body

   {
     "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
         }
       }
     ]
   }
   

2. Find from specific Webhook ID
   You can get details of a specific webhook with this API. Security token will be available in the response JSON message of that API.
   API Endpoint: /central/v1/webhooks/{wid}
   API Method: GET
   Base URL: https://apigw-prod2.central.arubanetworks.com
   (Replace the Base URL with correct API Gateway)
   Request Header: 'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
   Sample Response Body

   {
     "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
     }
   }
   

3. Get Webhook Token
   You can get just the security token of the webhook(based on the webhook ID) with this API.
   API Endpoint: /central/v1/webhooks/{wid}/token
   API Method: GET
   Base URL: https://apigw-prod2.central.arubanetworks.com
   (Replace the Base URL with correct API Gateway)
   Request Header: 'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'
   Sample Response Body

   {
     "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.

API Endpoint: /central/v1/webhooks/{wid}/token
API Method: PUT
Base URL: https://apigw-prod2.central.arubanetworks.com
(Replace the Base URL with correct API Gateway)
Request Header: 'Content-Type': 'application/json'; 'Authorization': 'Bearer <access-token>'

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

You can also find this API in our API Reference Guide here.