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.
Before enabling user import, follow the instructions specific to your identity provider:
To configure Azure AD for user and group import into Bold BI:
To configure Amazon Cognito via OAuth 2.0:
Additionally, to understand the overall embedding process with group-based authorization, refer to the following documentation:
To enable automatic user import, set the embed_user_import parameter to true in your embedding configuration.
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 | 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 |