Search results

Overview

This guide explains how to automatically import users from external identity providers when embedding dashboards using the Group-Based Authorization Overview approach through SDK embedding. This helps track which users are accessing embedded dashboards.

To enable this feature, configure your identity provider (e.g., Azure AD or Amazon Cognito) in the Bold BI server.

Identity Provider Configuration

Before enabling user import, follow the instructions specific to your identity provider:

Azure Active Directory (Azure AD)

To configure Azure AD for user and group import into Bold BI:

Amazon Cognito

To configure Amazon Cognito via OAuth 2.0:

Additionally, to understand the overall embedding process with group-based authorization, refer to the following documentation:

Enabling User Import

To enable automatic user import, set the embed_user_import parameter to true in your embedding configuration.

How to Set the Parameter

Include the embed_user_import parameter in your embedding authorization action method. This parameter allows Bold BI to automatically import users from the identity provider’s group when they access a dashboard for the first time.

By default, this parameter is set to false. It is optional, but required if you want auto-import functionality.

To configure your authorization server for user import via group-based authorization, include the parameters in the embedQuery.

v13.1

Node

const express = require('express');
const crypto = require('crypto');
const https = require('https');
const http = require('http');

const app = express();

app.post('/tokenGeneration', function (req, res) {
  // Required details
  const serverUrl = "<Bold BI Server URL>";
  const siteIdentifier = "<Site Identifier>";
  const serverApiUrl = serverUrl + "/api/" + siteIdentifier;
  const dashboardId = "<Dashboard Id>";
  const embedSecret = "<Embed Secret Key>";

  // Other required details
  const useremail = "<User Email>";  // Email of the third party user (not in Bold BI)
  const authProviderName = "<Auth Provider Name>";
  const userId = "<User Id>";

  // Build query string
  let queryString = "embed_nonce=" + crypto.randomUUID();
  queryString += "&embed_dashboard_id=" + dashboardId;

  // Add group-based authorization details to the query string
  queryString += "&embed_group_access=true";  // This property enables group-based authorization embedding
  queryString += "&embed_auth_provider=" + authProviderName;  // Provide auth provider name
  queryString += "&embed_user_id=" + userId;  // User id of the user
  queryString += "&embed_user_email=" + useremail;
  queryString += "&embed_user_import=true"; // This property enables user import in group-based authorization

  // Sign query string
  const embedSignature = "&embed_signature=" + getSignatureUrl(queryString, embedSecret);
  const embedDetailsUrl = "/embed/authorize?" + queryString + embedSignature;

  // Request token from Bold BI server
  const serverProtocol = new URL(serverApiUrl).protocol === 'https:' ? https : http;
  serverProtocol.get(serverApiUrl + embedDetailsUrl, function (resultContent) {
    let str = '';
    resultContent.on('data', chunk => { str += chunk; });
    resultContent.on('end', function () {
      const resultJson = JSON.parse(str);
      if (resultJson?.ApiStatus && resultJson.Data?.access_token) {
        res.json({ access_token: resultJson.Data.access_token });
      } else {
        res.status(500).json({ error: "Failed to generate embed token" });
      }
    });
  });
});

// Helper function: Sign query string using embedSecret
function getSignatureUrl(queryString, embedSecret) {
  const hmac = crypto.createHmac('sha256', Buffer.from(embedSecret));
  return hmac.update(queryString).digest('base64');
}

Example:
For GlobalOAuth: &embed_group_access=true&embed_auth_provider=GlobalOAuth&embed_user_id=1212121212&[email protected]&embed_user_import=true

v14.1

Node

var http = require("http");
var https = require("https");
var express = require('express');
var cors = require('cors');
var app = express();

app.use(cors());
// Parse JSON bodies (as sent by API clients)
app.use(express.json());

app.post('/tokenGeneration', function (request, response) {
  const embedDetails = {
    serverurl: "<Bold BI Server URL>",
    siteidentifier: "<Site Identifier>",
    dashboard: {
      id: "<Dashboard Id>"
    },
    embedsecret: "<Embed Secret Key>",
    email: "<Third Party User Email>",  
    groupbasedauthorization: {
        isenabled: true,
        userid: "<User Id>",
        authprovidername: "<Auth Provider Name>",
        isenableduserimport: true
    }
  }

  const parsedUrl = new URL(embedDetails.serverurl);
  const postData = JSON.stringify(embedDetails);
  const client = parsedUrl.protocol === 'https:' ? https : http;
  const options = {
    hostname: parsedUrl.hostname,
    port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
    path: `${parsedUrl.pathname}/api/${embedDetails.siteidentifier}/embed/authorize`,
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Content-Length': Buffer.byteLength(postData)
    }
  };

  const authRequest = client.request(options, authResponse => {
    let result = '';
    authResponse.setEncoding('utf8');
    authResponse.on('data', chunk => result += chunk);
    authResponse.on('end', () => {
      const resultparse = JSON.parse(result);
      response.send(resultparse?.Data?.access_token);
    });
  });

  authRequest.on('error', (e) => {
    console.error("Error fetching embed token:", e.message);
  });

  authRequest.write(postData);
  authRequest.end();
});

Example:
For GlobalOAuth:

email: "[email protected]",
groupbasedauthorization: {
    isenabled: true,
    userid: "1212121212",
    authprovidername: "GlobalOAuth",
    isenableduserimport: true
}
Parameter (v13.1) Parameter (v14.1) Description
embed_group_access groupbasedauthorization: { isenabled: } This parameter needs to set as true to enable the group-based authorization.
embed_auth_provider groupbasedauthorization: { authprovidername: } This parameter value indicates which auth provider you are using in embedding.

Following are the values for different auth providers:
AzureAD – Set this if you have configured AzureAD
TenantOAuth – Set this if you have configured OAuth at the tenant level
GlobalOAuth – Set this if you have configured OAuth at the global level
embed_user_id groupbasedauthorization: { userid: } Need to set your user id, which used in your provider for this user
embed_user_email email Need to set your user mail, which used in your provider for this user
embed_user_import groupbasedauthorization: { isenableduserimport: } The default value is false, and the parameter is optional. This parameter needs to be set as true to enable the auto import of the user into Bold BI from an external group.

NOTE: Please use your UserID and UserEmail as follows below.

Provider Parameter (v13.1) Parameter (v14.1)
Amazon Cognito Set the user email as embed_user_id and embed_user_email Set the user email as userid and email
Auth0 - Set the user id as embed_user_id
- Set the user email as embed_user_email
- Set the user id as userid
- Set the user email as email