Embedded Analytics - Security Matters

HTTPs

For security purposes, it is recommended to use HTTPS when embedding Holistics on your side.

Secret Key

The key we issue you in step 2 is to sign your payload with HMAC 256 signature mechanism. This signature is for us to check the payload's integrity and prevent people from tampering with and modifying your payload during the request.

Authentication

Mechanism

We use JSON Web Token (JWT) for user authentication. This is how it works:

• On the front-end side, Holistics dashboard is embedded into your website or application using iframe. The source link of the iframe contains an identification code (embed_code) of the dashboard, and a token which defines how your users can see the dashboard.
• The token is generated using JWT, from a payload containing your user's login name, dashboard settings, user permissions, filters, expired time... and the secret_key obtained when you enable embedding for your dashboard.
• Holistics then use this token to authenticate and figure out which user is logging in, and display your dashboard with only that customer's data.

Why JSON Web Token (JWT)?

Our Embedded feature is designed for multi-tenancy use case, where our customers want to embed a dashboard into their own application, and when their users log in they will see different data depending on their permissions.

With a token generated with JWT, you can identify your users and ensure they can only see the data they are allowed to. Users cannot simply change URL parameters to pull any data points they want, since their permission is baked into the token. They also cannot tamper with the token's content, since Holistics can verify the integrity of the content and disregard tampered tokens.

Token Expiration

You must specify a time to expire your issued JWT. The recommended expiration time is 24 hours after you issue the token.

This is a precaution against the situation when someone steals your user's token (which is not difficult to do), uses it to assume your user's identity, and accesses their data illegally.

When the token has a short expiration time, the damage is minimized.

Sensitive Data

Note that the JWT only allows us to check the integrity of the received payload. No cryptography is involved in JWT, which means your payload's information is not concealed from others.

danger

Please do not include any sensitive data (for example, user's password) inside the payload.

Enforcing Data Access Control the right way

Although it seems that both Permission Settings and Controls Settings can restrict user's access to data, in reality, they serve two different purposes.

Here is the general rule of thumb to help you decide which one to use:

• Permission Settings should be used if you want to enforce data access restriction on your embedded analytics viewers so that they can only view a subset of your data.

  Notes

  Permission Settings should always be used for security best practices.

• Controls Settings is a convenient method to set up default new values for your embedded dashboard. It helps you override existing dashboard filters' default values, as well as hide some filters to make your customer-facing dashboards cleaner.

  Important

  Although we do not provide the UI for the embedded viewers to modify these settings' values, it is still possible for users to tamper with these values on their ends.

The differences between the two settings are summarized below.

	Permission Settings	Controls Settings
Purpose	Data Access Control	Override filter values or hide filters for aesthetics purposes
Data Restriction Level	Dataset level (Strict)	UI only (Can be tampered)

Let's demonstrate their key differences by inspecting a dashboard with multiple country values as shown in the example below. If you set the Permission Setting for country_name to Vietnam, your country filter will only show the value Vietnam. It will return no value if you try to change the filter value to another value other than Vietnam.

By contrast, if you pick Controls Settings to restrict access, clever users can tamper with the country_name and can access unauthorized data from other countries.