User-Backed Embedding

This is a Premium Feature.

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
      Impact of Changes to the Underlying Workbook
Related Resources

Requirements

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. 

Learn more about permissions in Sigma

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.

Learn more about 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 embed user saved workbook versions. They can not be sent from the original embedded workbook version.

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.

  1. Generate an Embed Secret
  2. Create a Space for Your Embed Users
  3. Prepare Your Workbook & Implement RLS
  4. Create an Embed URL
  5. 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:

  1. Open your Admin Portal.
  2. Click Teams to open the Teams page
  3. Click Create Team.
  4. Set a team name and description.
  5. [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.

  6. 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:

  1. If you want to enforce RLS, create a Sigma dataset and implement dataset RLS.
    Note: Save the dataset outside of the team workspace.
  2. Create your workbook:
  3. 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.

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. The following instructions will show you how to create and application embed URL: Create an Application Embed URL

Now what? Add an Embed to your Application

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. 

  1. In Snowflake, leverage row-access policies that are defined for individual embedded users.

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

  3. 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:

To add the embed to your application:

  1. Add a server-side API to your application.
    This API should generate a secure embed URL.
  2. 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

 

The following parameters are required:

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

    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
  • <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).
  • <user_email> [required] - The email address that will be 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()
  • <themes> [required] - 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.

The following parameters are optional to be included:

  • <account_type> [optional] - By default, all embed users are granted Explorer permissions. Users can also be assigned creator permissions or a custom account type. This parameter  must be lowercase. The possible values are: creator, viewer, or custom.
  • <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.
    Learn more about user attributes and CurrentUserAttributeText()
  • <nonce> - A random unique string (less than 255 characters). Sigma uses this to prevent application embed URLs from being shared and reused.
  • <unix_timestamp> - 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.
  • <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. This will allow you to customize what your viewers see. Learn more
  • <showUnderlyingData> set to false to hide underlying data from embed users with explore access.
  • <show_footer> [optional] defaults to true, when set to false will hide 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. This is also available for application embeds.
  • <responsive_height> [optional] If set to true the height of the iFrame will adjust to the size of the content. In addition, 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.

    company apps

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

Node.JS Example of Server-Side API Definition

const createHmac = require("create-hmac");
const uuid = require('uuid');

const mode = "userbacked";
const user_email = "test@sigmacomputing.com";
const user_id = 619;
const teams = "testt";
const attribute_name = "region";
const attribute_value = "thisworks";
const account_type = "creator";

// :nonce - Any random string you like but cannot be repeated within the hour.
let searchParams = `?:nonce=${uuid.v4()}`;

// :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. Learn more

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.

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 learn more about using this interface, visit Interact with User-Backed Embeds.

2022-06-08_13-14-47__1_.gif

Impact 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