Search results

Dashboard Embedding with Token Authentication

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

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 as follows:

Parameter Description
dashboard URL URL of the dashboard to be embed. Please refer to the Get links to Dashboards.
Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis

embed parameters Mandatory Parameters to embed the dashboard 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 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?embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

NOTE: By default, the generated Iframe signature URL is valid for an indefinite amount of period. In mean time, you can secure your Iframe URL with allowed domains and IP addresses support. Please refer to the Secured Embedding for more.

NOTE: If you want to enable the validation and expiration for generated URL, you can set the embed_timestamp and embed_expirationtime parameters.

Optional Embed Parameters

Please find the optional dashboard embed parameter specifications below. Here you may find 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
embed_dashboard_views This value makes you to check the views in the embedded dashboard. The default value is true. To disable or hide the view icon from the toolbar, you can set the value of the embed_dashboard_views parameter to false. true
embed_dashboard_views_edit This value allows you to perform the actions such as save view, update view, and delete views in the embedded dashboard. The default value is true. To disable or hide the Save and SaveAs icon in the filter overview, you can set the value of the embed_dashboard_views_edit parameter to false. true
embed_dashboard_export The export option to various formats of the dashboard and widget in 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_dashboard_comments The actions related to comments such as post, edit, delete, reply, watch, un-watch, posting the image, and user mention list options can be performed in the dashboard 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_dashboard_edit Show/hide the dashboard edit icon. By default the icon will be shown only if user has the permission to edit the specific dashboard otherwise it doesn't shown. false
embed_dashboard_favorite We have option to mark the dashboard as favorite. The default value is true and icon would show. To disable or hide the dashboard favorite icon from the toolbar, you can set the value of the embed_dashboard_favorite parameter to false. true
hide_header This value allows you to show the dashboard header. The default value is false. To hide the header of the dashboard, you can set the value of the hide_header parameter to true. false
hide_tool This value allows you to show the dashboard icons in the toolbar. To hide specific dashboard icons from the toolbar, you can set the value for the "hide_tool" parameter with predefined values that corresponds to each icon in the toolbar.

Note: Predefined values: tm-Theme,dp-Dashboard Parameter,fo-Filter Overview,fs-FullScreen,rf-Refresh,om-Option Menu

string.
Example:
hide_tool= "tm,dp,fo,fs,rf,om".

embed_datasource_filter The embedded dashboard can be filtered with passed Dashboard Parameter and URL Parameter. `If you would like to pass Dashboard Parameter - embed_datasource_filter=&&DashboardParameter1=Value1`
`If you would like to pass URL Parameter - embed_datasource_filter=&URLParameter2=Value2`
`If you would like to pass both Dashboard and URL parameter - embed_datasource_filter=&&DashboardParameter1=Value1&URLParameter2=Value2`

Sample application for Dashboard Embedding with Token Authentication

Please get the Dashboard 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 the code sample to generate the signature in C#. You can write the equivalent code in your platform 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=
       }
    }

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, 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’.

Create the embed URL to Edit Dashboard

The embed URL should be in the following format.

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

Please find the details of the parameter in the URL as follows.

Parameter Description
dashboard edit URL URL of the editable dashboard. Open the dashboard in edit mode to obtain the dashboard designer URL. Copy the URL to embed the specific dashboard once it has been opened on the designer page.
Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboard-designer/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis

embed parameters Mandatory Parameters to embed the dashboard in design mode 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 Embed Secret key. Both are not same.
Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

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

Example: https://test.boldbi.com/bi/en-us/site/site1/dashboard-designer/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis?embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

Create the embed URL to Create Dashboard

The embed URL should be in the following format.

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

Please find the details of the parameter in the URL as follows.

Parameter Description
create dashboard URL URL to create a new dashboard.
Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboard-designer

embed parameters Mandatory Parameters to embed the dashboard in create mode 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 Embed Secret key. Both are not same.
Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

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

Example: https://test.boldbi.com/bi/en-us/site/site1/dashboard-designer?embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY='

How to enable token validity and expiration time in embed URL

The embed_timestamp parameter is used to set token validity. The value is the UNIX timestamp of the current time(embed_timestamp=1583928213). If you set this, the generated iframe URL is valid only for 6 days. For more detail please check the above Optional Parameter section.

This example illustrates about generating the URL with 6 days validity, after that period the URL wouldn't be work: https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis?embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_timestamp=1583928213&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

The embed_expirationtime is used to set the expiration time of the iframe signature URL. If needed, can expire the URL within the token validity period of 6 days. It has to be declared in seconds(embed_timestamp=1583928213&embed_expirationtime=86400) but not greater than value of 518400 seconds which represent token validity as 6 days. For more detail please check the above Optional Parameter section.

This example illustrates about generating the URL with expiration time. Here I have set 1 day as expiration in seconds, after that period the URL would be expired and won't work: https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis?embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_timestamp=1583928213&embed_expirationtime=86400&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

How to pass the dashboard parameter and URL parameter filters in embed URL

In the embed URL, you can simultaneously pass values for both types of filters (Dashboard Parameter/URL Filter Parameter).

Pass your filters to the embed_datasource_filter=&&dashboardparameter1=value1&urlparameter1=value1 URL parameter in the embed URL as follows.

Example: https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis?embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com&embed_datasource_filter=&&dashboardparameter1=value1&urlparameter1=value1&embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=
  • In the embed URL, the dashboard parameter filter must be started with a double ampersand &&. For more details, Refer to the configuring dashboard parameters.

  • In the embed URL, the URL filter parameter must be started with a single ampersand &. For more details, please refer to the URL Filter.