User-Backed Embedding

Sigma user-backed embedding is a Premium Feature that is not included in the base license. Contact your Sigma Representative for more information.

This document explains how to set up user-backed embedding for your organization and adding user-backed embeds to your application(s).

User-backed embedding is a form of application embedding. Unlike Sigma's standard application embedding feature, each embed consumer is treated as an individual, with an account type and team permissions. We refer to these individuals as embed users.

You can also allow embed users to save and edit their own versions of embedded workbooks.

Summary of Content

Requirements
Considerations
Save and edit
CSV uploads
Scheduled exports
Row-level security
Get Started
Create a Space for Your Embed Users
Create a New Team & Workspace
Prepare Your Workbook & Implement RLS
Create an Embed Path URL
OAuth for Embeds
Add an Embed to Your Application
Add a Server-Side API to your Application
Node.JS Example of Server-Side API Definition
Call the API from Your Client & Render the Embed
Example of Client-Side Iframe Creation
JavaScript Events
Consumer Facing Result
Effect of Changes to the Underlying Workbook
Related Resources

Requirements

To set up this feature for your organization, you must be an Admin.
Depending on your role, engineering support may be needed to add the embed to your application.

Considerations

Do you want to allow your embed users to save and edit their own versions of an embedded workbook?

Users with creator and custom account types that support editing workbooks, can save versions of embedded workbooks to their My Documents folder, if they or their team have edit access to the workbook.

To save workbooks to a shared workspace, a user must also have Can Contribute access to the workspace. This access can be granted on the team or individual user level. See Folder and document permissions

Do you want to allow your embed users to upload CSVs?

To upload a CSV, a user must be assigned a creator account type or a custom account type that allows CSV uploads. They must also have access to at least one table in a write access enabled connection.

If you don't want to grant users access to any of the data in your connection, we recommend creating a dummy table in your warehouse and grant the user(s) access to just that table; see CSV uploads.

Do you want to allow your embed users to schedule exports?

To send and schedule exports, a user must be assigned a creator, explorer or custom account type that allows scheduled exports.

Exports can only be scheduled from full embedded workbooks. If you are embedding single pages of a workbook or single elements, embed users will need to Save As to create a workbook the scheduled export can be associated with.

Do you want to enforce row-level security?

Datasets should be used to implement all RLS in user-backed embedded workbooks.

Workbook-level RLS should not be used for this feature.

Get Started

The following steps will guide you through how to set up user-backed embedding, from initial admin setup to adding an embedded workbook to your application.

Generate an Embed Secret
Create a Space for Your Embed Users
Prepare Your Workbook & Implement RLS
Create an Embed URL
Add the Embed to Your Application

Create a Space for Your Embed Users

To view and interact with user-backed embedded workbooks, a user must be assigned to at least one team in your organization. You must create this team before setting up your embed. However, you don't need to manually invite embed users to your organization and team. Their accounts are created when they open a user-backed embed.

For team members or individual users to save and edit versions of embedded workbooks, they must have Can Contribute access to a workspace.

Create a New Team & Workspace

To create a new team and workspace:

Open your Admin Portal.
Click Teams to open the Teams page
Click Create Team.
Set a team name and description.
[Optional] Select Create a Workspace associated with this Team.

All team members are automatically granted Can Contribute access to the workspace. This permission can be revoked at any time.
Click Save.

Prepare Your Workbook & Implement RLS

Prerequisite: A dedicated space for your embed users

To implement RLS, create your workbook, and grant permissions to your data:

If you want to enforce RLS, create a Sigma dataset and implement dataset RLS.
Note: Save the dataset outside of the team workspace.
Create your workbook:
- from your Sigma dataset(s) OR
- from data in a warehouse table(s)
  Note: Save your workbook outside of the team workspace.
Grant the embedded users' team access to the workbook and its data sources.
Grant access to the workbook (Can Edit, Can Explore, or Can View)
Grant Can View access to dataset(s)
Grant Can View access to warehouse table(s)

Now what? Create an Embed URL. Include the parameter(s) associated with the dataset's RLS. The following list matches identifying columns used in RLS with their embed parameter counterparts.

CurrentUserEmail() with <user_email>
CurrentUserInTeam() with <external_user_team>
CurrentUserAttributeText() with <user_attribute>

Create an Embed Path URL

Prerequisite: The workbook from which you want to create an embed

User-backed embeds are created using application embed URLs. You can create them for full workbooks, single-workbook pages, and individual workbook elements.

If you want to expose a specific Version Tag of a Workbook, you need to append /tag/{tagName} to the application embed URL path.

Example syntax: https://app.sigmacomputing.com/embed/3AYgZn4Tww1EbpvaMpLtq7/tag/Production

OAuth for Embeds

This feature allows embedding customers to enhance authentication security using OAuth. See our complete documentation for OAuth with Snowflake.

You can pass secure tokens to Sigma that authenticates users into Sigma's embedded analytics to drive granular user permissions.

Follow the steps below to use OAuth for Embeds.

In Snowflake, leverage row-access policies that are defined for individual embedded users.
Encrypt the token using AES with the same embed secret string that you generated for this embed in the API & Embed Secrets tab in Sigma's admin portal.
Enter the <oauth_token> parameter into the embed URL. See Add a Server-Side Application for more context.

Add an Embed to Your Application

Prerequisites:

An embed secret
An application embed URL
Access to edit your application's code OR a friendly developer

To add the embed to your application:

Add a server-side API to your application.
This API should generate a secure embed URL.
Call the API from your client and render the embed

Add a Server-Side API to your Application

A server-side API must be added to your application for the purpose of generating a secure embed URL. View our Node.js example

The generated URL will have the following structure:

<workbook_embed_path>?:nonce=<random_nonce_value>&:time=<unix_timestamp>&:session_length=<session_length>&<control_id>=<control_value>&:external_user_id=<external_user_id>&:signature=<hmac_signature>&:mode=userbacked&:client_id=<client_Id>&:external_user_team=<external_user_team>&:email=<user_email>&:account_type=<account_type>

Example:

https://app.sigmacomputing.com/embed/1qmpD5yiMIRvb6dI8l4pzK?:nonce=35df8548-c7e5-4d35-92da-7f8114843999&:session_length=3600&:client_id=9319bfb04ae48af48bbee8f702669c085a38b6a73f43d32htd70a3cd6ee4h9iu&:time=1654709460&:external_user_id=12&:external_user_team=Team%20A%2CTeam%20B&:email=harold@mycoolcompany.com&:account_type=creator&:mode=userbacked&:signature=j323557c82b26103faf65314db41ebc51ea9n3a61795ef22f45ep0aed1f4182493

Required Parameters

<workbook_embed_path> [required] - The workbook generated application embed URL.
<embed secret> and <client id> [required] - Use the <embed secret> to generate your <hmac_signature> in your server. This must be encoded in hexadecimal.

A <client_id> is only required if the secret is generated from your Admin Portal’s APIs & Embed Secrets page. Secrets created from the Account page do not have an associated <client_id>

If the embed secret is generated from your Admin Portal's Account page, this value isn't applicable. However, secrets generated from the APIs & Embed Secrets page have a required corresponding client_id.
<external_user_id> [required] - A unique identifier for each individual using the embed. Sigma uses this identifier for licensing purposes.
<mode> [required] - Set to userbacked.

User types <mode> can't be changed after they're created. When you create a user, they're assigned one of the three user types: internal, guest, and embedded (user-backed). For example, if you create an internal user, you can't change the user to embedded later.
<external_user_team> [required] - The name of your embedded users' team(s) (e.g. Team%20A%2CTeam%20B). For RLS, use with CurrentUserInTeam()
<session_length>[required] - The number of seconds the embed URL should remain valid after the application embed URL was generated. After the specified number of seconds, the Application Embed will no longer display new values. The maximum session length is 2592000 seconds (30 days).
<unix_timestamp> [required] - The current time as a UNIX timestamp. Sigma uses this in combination with the <session_length> to determine if your link has expired. The URL is valid after the <unix_timestamp> and before the <session_length> expiration.
<user_email> [required] - The email address associated with the user’s account.
Email addresses already associated with a standard (not embed) user account will not be considered valid. For RLS, use with CurrentUserEmail()
<nonce> [required] - A random unique string (less than 255 characters). Sigma uses this to prevent application embed URLs from being shared and reused.

Optional Parameters

<account_type> [optional] - This value will either set or overwrite an embed user's account type. You can use any user account type your org has created except Admin. If <account_type> is not included or a value isn't provided, then a default user account type called embedUser will be set. The permissions for embedUser are listed below and cannot be edited.
<user_attribute> [optional] - A user attribute {key: value} pair to be applied for RLS. In the URL, include an independent :ua_<attribute> parameter for each attribute you want to use. This isn't case sensitive. See User attributes and CurrentUserAttributeText().
<control_id> and <control_value> [optional] The ID and value of any existing workbook control you want to pass through to the workbook. You may pass multiple control IDs and values, to customize the visibility of elements for the viewers
<showUnderlyingData> [optional] -Set to false to hide underlying data from embed users.
<show_footer> [optional] Defaults to true. If set to false, it hides the file explorer, workbook page tabs, and "Save As" / "Edit" options.
<hide_tooltip> [optional] If set to true and a user hovers over a tooltip, the tooltip is no longer displayed. This applies to vega charts (line, bar, area, etc) and map chart marks.
<responsive_height> [optional] If set to true this allows developers access to workbook:pageheight:onchange JavaScript event.
<hide_folder_navigation> [optional] Available for <mode=userbacked>, if set to true, it hides the folder navigation options in the bottom left.
<oauth_token> [optional] Passes a secure token to Sigma that authenticates users into Sigma's embedded analytics to drive granular user permissions. See OAuth for Embeds for configuration instructions.
<theme> [optional] Use any of the default themes (Light, Dark, and Surface) or any themes defined in your org. Use the name of the theme as the value. The value is case-sensitive. For example: Light%20Palette%201.
<disable_mobile_view> [optional] If you set this boolean parameter to yes, workbooks won't automatically resize to the mobile layout.
<hide_workbook_name> [optional] [beta] A boolean value that hides the workbook name near the folder icon.
<menu_position> [optional] Allows you to change the position of the toolbar to top, bottom, or none. none removes the toolbar. If this value isn't set, it defaults to bottom.
<loading_bg> & <loading_text> [optional] Allows you to change the background and font colors respectively on the loading and error screens when used with hex color codes. example: :loading_bg=2DBBAB
<hide_menu> [optional] If set to True, hides the menu in the bottom-left for saved workbooks.
<hide_send> [optional] If set to True, hides the Send now option in the menu for saved workbooks.
<hide_schedule> [optional] If set to True, hides the Schedule exports option in the menu for saved workbooks.

Node.JS Example of Server-Side API Definition

const createHmac = require('create-hmac'); 
const uuid = require('uuid'); 
 
const EMBED_PATH = 'INSERT EMBED PATH HERE'; 
const EMBED_SECRET = 'INSERT EMBED SECRET HERE'; 
const client_id = 'INSERT CLIENT ID HERE'; 
const mode = 'userbacked'; 
const user_email = "<mailto:test@sigmacomputing.com|test@sigmacomputing.com>"; 
const user_id = 619; 
const teams = "test_team"; 
const account_type = "creator"; 
const attribute_name = "region"; 
const attribute_value = "thisworks";  

// :nonce - Any random string you like but cannot be repeated within the hour 
let searchParams = `?:nonce=${uuid.v4()}`;
  
// :client_id - The unique identifier associated with your embed Secret 
searchParams += `&:client_id=${client_id}`;
  
// :mode - set to "userbacked" 
searchParams += `&:mode=${mode}`;
  
// :email - The email address that will be associated with the user's account 
searchParams += `&:email=${user_email}`;
  
// :external_user_team - The name of your embedded users' team(s). (e.g. Team%20A%2C%20Team%20B) 
searchParams += `&:external_user_team=${teams}`;
  
// :ua_<user_attribute> - [optional] - A user attribute to be applied for RLS; for each independent attribute, use a :ua_<attribute_name> parameter // 
searchParams += `&:ua_${attribute_name}=${attribute_value}`
  
// :account_type - [optional] By default, all embed users are granted Explorer permissions. Format lowercase (e.g. "viewer", "creator") 
searchParams += `&:account_type=${account_type}`;
  
// :session_length - The number of seconds the user should be allowed to view the embed 
searchParams += '&:session_length=3600';
  
// :time - Current Time as UNIX Timestamp 
searchParams += `&:time=${Math.floor(new Date().getTime() / 1000)}`;
  
// :external_user_id - a unique JSON string identifying the viewer 
searchParams += `&:external_user_id=${user_id}`;
  
// EMBED_PATH - Generated on your workbook 
const URL_WITH_SEARCH_PARAMS = EMBED_PATH + searchParams;
  
// EMBED_SECRET - Sigma Embed Secret generated in your admin portal 
const SIGNATURE = createHmac("sha256", Buffer.from(EMBED_SECRET, "utf8"))  
.update(Buffer.from(URL_WITH_SEARCH_PARAMS, "utf8"))  
.digest("hex");  

const URL_TO_SEND = `${URL_WITH_SEARCH_PARAMS}&:signature=${SIGNATURE}`
  
console.log(URL_TO_SEND);

Call the API from Your Client & Render the Embed

Prerequisite: a server-side API in your application that generates a secure embed URL

Once the API has been added to your application, you will need to call it from the client. The client will pass the embed path to the API, and the server will respond with the secure embed URL. The client can then render this embed URL in an iframe.

Optional: After the embed URL is generated, your application’s client can interact with its iframe through JavaScript actions and events. Events will allow the client to listen for variable updates that it can then use to take actions, such as passing control values to different embeds or from one of your application’s widgets to an embed.

Example of Client-Side Iframe Creation

// YOUR_API_URL will be the url the API defined in the server-side code 

const resp = await fetch(YOUR_API_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': token,
  },
  body: {}
});

const embedUrl = resp.data;
<iframe
  title="your-signed-embed"
  style={{
    display: "block",
    height: "100%",
    width: "100%"
  }}
  frameBorder="0"
  src={embedUrl}
/>

JavaScript Events

After the embed URL is generated, your application’s client can interact with its iframe through JavaScript actions and events. Events will allow the client to listen for variable updates that it can then use to take actions, such as passing control values to different embeds or from one of your application’s widgets to an embed.

Accessing Events in JavaScript

Example of listening for JavaScript events from Sigma:

window.addEventListener('message', function (event) {
  if (
    event.source === document.getElementById('sigma-iframe').contentWindow &&
    event.origin === "https://app.sigmacomputing.com"
  ) {
    console.log(event.data);
  }
});

Events

Currently Sigma has two types of events:

workbook:loaded

This event is created when a workbook has finished loading the metadata but has not started evaluating the workbook elements.

{
  type: 'workbook:loaded',
  workbook: { variables: encodedVariables },
}

workbook:pageheight:onchange

This event is only shown when <responsive_height> parameter is set to true and is created when an action results in a change of iFrame height.

{
  type: 'workbook:pageheight:onchange',
  pageHeight: integer
}

workbook:variables:onchange

This event is triggered whenever a control/variable has been updated within Sigma’s iFrame through User interaction.

{
  type: 'workbook:variables:onchange',
  workbook: {
    variables: {'Variable1': 'value1', 'Variable 2': 'value2' }
  },
}

Attribute	Format	Description
workbook.variables	Object	The variables applied to the workbook with the format { ‘Variable Name’: ‘value1’, ‘Variable Name2’: ‘value2’ } Note that the values are URL encoded. Please see Workbook Controls in the URL for examples on how the values are encoded for the URL.

Attribute

Format

Description

workbook.variables

Object

The variables applied to the workbook with the format

{ ‘Variable Name’: ‘value1’, ‘Variable Name2’: ‘value2’ }

Note that the values are URL encoded. Please see Workbook Controls in the URL for examples on how the values are encoded for the URL.

Consumer Facing Result

The gif below shows an example of the interface your embed users will see. In this example, the user is permitted to save and edit workbook versions in their shared workspace.

To understand how to use this interface, see Interact with User-Backed Embeds.

Effect of Changes to the Underlying Workbook

Changes published to a workbook in Sigma are automatically represented in the original embedded version of the workbook. However, they do not trickle down to embed users’ existing saved versions of the embedded workbook.

Related Resources

Application Embedding
Interact with User-Backed Embeds

Was this page helpful?

Yes No