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}]"
}
Updated over 2 years ago