Documentation
Demos
Support
Blog
Start Free Trial
Search results

Widget Embedding with Token Authentication

Bold BI supports embedding widgets with iFrame using token-based authentication.

How to get the Embed Widget Url

  1. Open the desired dashboard and select the More option under the widget you want to embed .Then, select Get Embed Code from the drop-down menu. InspectElement

  2. Copy the iframe code from the embed code pop-up page. InspectElement

Create the embed URL to View Dashboard

The embed URL should be in the following format.

{dashboard URL}/{embed parameters}&embed_signature={signature}

Please find the details of the parameter in the URL below.

Parameter Description
dashboard URL URL of the dashboard widget to be embed. Please refer to the Widget Embedding to get the URL. 
Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis?isWidgetMode=true&widgetId=0000aeab-3359-40c6-b014-1ea98e9a7ce9&
embed parameters Mandatory Parameters to embed the widget with token based authentication.
embed_nonce Random GUID string that restricts the URL reconstruction or attacks from the hackers. 3e253410-1a82-4fb3-a337-122a8007dafc
embed_user_email User email id. admin@domain.com 
Example:
embedParameter="embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com"
embed signature This embed signature is generated by encrypting the above embedParameters query string using the `HMACSHA256` algorithm.
Note:Embed signature is different from the Embed Secret key. Both are not same. 
Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

The following embed URL is the formation of the dashboard URL, embed parameters, and embed signature

Example: https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis?isWidgetMode=true&widgetId=0000aeab-3359-40c6-b014-1ea98e9a7ce9&embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

NOTE: The generated iframe signature URL is valid indefinitely because the embed_timestamp and embed_expirationtime parameters are optional. If you want to set the default validity period of 6 days for the generated iframe URL, use the embed_timestamp.

Optional Embed Parameters

Please find the optional widget in the embed parameter specifications below. Here, you may find the EmbedProperties for the dashboard.

Parameter Description Example
embed_timestamp A UNIX timestamp of the current time. This is used to verify that the embed URL was established within the last 6 days.
double unixTimestamp = (DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds.		 1583934776
embed_expirationtime Decide how long the token will remain active than default 6 days. It has to be portrayed in seconds. The time ranges from 86400 seconds (one day) to 518400 seconds (six days). If you want to set embed_expirationtime, you must set the embed_timestamp too in the URL generation. 518400
isWidgetMode To enable the widget mode. true
widgetId Widget Id of the dashboard widget to be embedded. To know how to get widgetId from the dashboard, refer to theWidget Embedding 0000aeab-3359-40c6-b014-1ea98e9a7ce9
embed_dashboard_export The export option to various formats of the dashboard and widget in the embedded dashboard is displayed based on this value. The default value is true. To disable or hide the export icon from the toolbar, you can set the value of the embed_dashboard_export parameter to false. true
embed_widget_comments The actions related to comments such as post, edit, delete, reply, posting the image, and user mention list options, can be performed in widgets based on this value. The default value is true. To disable or hide the dashboard comments icon from the toolbar, you can set the value of the embed_dashboard_comments parameter to false. true
hide_widget_tool This value allows you to show the widget icons in the widget header. To hide specific widget icons from the widget header, you can set the value for the hide_widget_tool parameter with predefined values that correspond to each icon in the widget header.

Note: Predefined values: fr-Filter,fs-FullScreen,om-Option Menu

 string. 
Example:
hide_widget_tool= "fr,fs,om".

Sample application for Widget Embedding with Token Authentication

Please get the Widget Embedding with Token Authentication sample from GitHub.

Generating the embed signature for the embed URL

Embed parameters and the Embed Secret Key are mandatory parameters used for generating the Embed Signature

We have provided a code sample for generating the signature in C#. You can write the equivalent code in your platform’s language.

    var embedParameters = "embed_nonce=55a1c8f4-5015-487d-8463-d3ebeae655fd&embed_user_email=admin@domain.com";
    var embedSecretKey = "7tFaq2zidmxJN8Pid6IUAiGFqAUwMfK"; //site-administration/embed-settings/#get-embed-secret-code

    public string GetSignatureUrl(string embedParameters, string embedSecretKey)
    {
       var encoding = new System.Text.UTF8Encoding();
       var keyBytes = encoding.GetBytes(embedSecretKey);
       var messageBytes = encoding.GetBytes(embedParameters);
       using (var hmacsha = new HMACSHA256(keyBytes))
       {
        var embedSignature = hmacsha.ComputeHash(messageBytes);
        return Convert.ToBase64String(embedSignature);
        // For eg, embedSignature = VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=
       }
    }

The term Embed Signature refers to a hashed value that is generated for authentication purposes in an embed request sent to the Bold BI server. To obtain the embedSignature, the embedParameters(contains dashboardid, widgetid, user email and other parameters) and embedSecretKey are passed as arguments to the GetSignatureUrl method. This method generates the hashed signature using the HMACSHA256 algorithm, which should be appended to the existing iframe URL as a query parameter named ‘embed_signature’.

Previous
Next