Belltastic Documentation

HMAC authorization

Why is it necessary

Because the notification component and operates in a browser, you can only hope that your users will not tamper with it and start changing its properties in order to retrieve another user's or project's notifications.

To prevent this from happening, it is highly recommended for you to enable HMAC authorization for your project used in production.

Enabling HMAC Authorization

You can do that by navigating to selected project's settings and turning on "HMAC Authorization" for that project.

When it is enabled, you will be required to provide a calculated HMAC hash to the notification component's user-hmac property, like so:

<belltastic-notifications
    ...
    user-hmac="{CALCULATED_HMAC}"
></belltastic-notifications>

Calculating HMAC

WARNING

Please perform this calculation on the server (back-end) so that the Project Secret does not leak to your users, otherwise they can forge HMAC hashes for different users and retrieve notifications that do not belong to them.

Your language of choice should have the tools available to calculate the correct HMAC for the given project and user. Here's an example of how to calculate it using PHP:

// For this calculation you will need:
// - ID of the Belltastic project
// - ID of your user
// - Project's "secret" which you can find in project settings

$calculated_hmac = base64_encode(hash_hmac(
    'sha256',
    $project_id . ':' . $user_id,
    $secret,
    true
));

// => "xMHdtqGGI2LoOQ3eKd4v8Z+4ieK3Nj+7ZxkOwhXG4qA="

Or, if you're using our Laravel packageopen in new window, you can easily get the HMAC calculated like so:

$calculated_hmac = \Belltastic\User::hmac($project_id, $user_id);

// => "xMHdtqGGI2LoOQ3eKd4v8Z+4ieK3Nj+7ZxkOwhXG4qA="

The resulting Notification Component will look like so:

<belltastic-notifications
    ...
    user-hmac="xMHdtqGGI2LoOQ3eKd4v8Z+4ieK3Nj+7ZxkOwhXG4qA="
></belltastic-notifications>

WARNING

Make sure to not hardcode this value in your code. Because it depends on the Belltastic's project ID and your user's ID, the calculated hash will be different for every user.