Create a secure embed

Secure embedding allows you to securely integrate Sigma content (an entire workbook, specific page, or individual chart or table element) into another application without requiring users to authenticate through Sigma. The secure embed inherits the host application's user security configurations at runtime to implement the appropriate level of control over access to Sigma content.

This document provides an overview of the workflows required to create a secure embed.

System and user requirements

The ability to create and manage secure embeds requires the following:

• Secure embedding is a premium feature and must be enabled for your organization.
• You must be assigned the Admin account type and have been granted embedding credentials by an admin. See Generate embed client credentials for more information.

📘

Depending on your technical expertise and access to the host application, you may require assistance from your Engineering team when completing the server-side requirements.

Choose a secure embed method

This document provides an overview of the workflow required to create a secure embed with one of two secure embedding methods:

1. Sign your secure embed URLs with JSON Web Tokens (JWTs).
2. Secure your embed URL without using JWTs. In this case, you sign the URL with your client ID and embed secret.

Signing your secure URLs with JWTs has several advantages:

• JWTs are compact, URL-safe tokens that can be digitally signed, ensuring that the data they contain is tamper-proof.
• Embed developers no longer have to use the Sigma UI to generate embed paths; they may use the URL instead.
• JWT URLs can authenticate internal Sigma users to access embedded content with the same email address they use for their Sigma account.
• When using JWT URLs, you have the option to disable automatic embed user account provisioning for non-Sigma users, effectively restricting your embed content to the users you have explicitly provisioned in Sigma or your IdP.

Workflow to create a secure embed

1. Generate embed client credentials. The client credentials (a unique client ID and client secret) are required to authenticate and authorize the embedded Sigma content in the host application.

2. Create a team for embed users. Secure embedding requires at least one team in Sigma to facilitate group-level access to the embedded Sigma content. This team can also optionally support workspaces and data permissions for embed users.

3. Prepare your embed URL.

   1. For embeds signed with JWTs: Build a base URL by copying the published link that points to the Sigma content you want to embed.
   2. For embeds not signed with JWTs: Generate a secure embed path that points to the Sigma content you want to embed.

4. Test the embed in Sigma’s embed sandbox. Configure and test optional interface, security, and user attribute parameters.

5. Create an embed API to interact with Sigma's services. This API manages requests and responses between the host application and Sigma.

   1. For embeds signed with JWTs, see Example embed API via JWT secure method.
   2. For embeds not signed with JWTs, see Example embed API and URL.

6. Implement your API to render the Sigma content in the host application interface.