Embedding with Token Authentication

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:

Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboards/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis

Example:
embedParameter="embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com"

Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

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

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.

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

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.

Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboard-designer/8428c9d9-85db-418c-b877-ea4495dcddd7/Predictive%20Analytics/Personal%20Expense%20Analysis

Example:
embedParameter="embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com"

Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

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

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.

Example:
https://test.boldbi.com/bi/en-us/site/site1/dashboard-designer

Example:
embedParameter="embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com"

Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

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

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.

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.

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.

• 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.

Embed data source with token in Bold BI

Bold BI supports embedding the data source into other web applications using Token authentication.

Steps to embed data source

The following steps outline how to embed a data source into other web applications.

Get embed secret code

1. Go to the settings page and click on Embed. Enable the Enable embed authentication under that page.

   

2. Click Generate Secret button.

   

3. When you click on it, the secret code will be generated. Be sure to save the secret key securely as it cannot be retrieved or restored once the secret is generated.

   

4. After generating the secret code, it can be regenerated by clicking the Regenerate Secret button.

   

Warning : Resetting this code will cause the previously functioning embedded dashboards to stop working.

Creating the embed URL to create data source

The embed URL should be in the following format; to get create datasource URl, Please refer the Get Data source URL.

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

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

Creating the embed URL to edit data source

The embed URL should be in the following format; to get edit datasource URL, please refer the Get Data source URL.

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

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

Sample to embed data source in edit mode using Token authentication

You can download the sample.

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.

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

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.

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&

Example:
embedParameter="embed_nonce=3e253410-1a82-4fb3-a337-122a8007dafc&embed_user_email=admin@domain.com"

Example:
embed_signature=VYrDMVX4h85PrRBKX9mystRHYkU8z+HVC9bkVMc2qGY=

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

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.

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.