Setup Guide - Sigma Computing Embedded Analytics for Confluence¶

This guide helps you quickly deploy and start using Sigma Computing Embedded Analytics for Confluence. Sigma connects to popular data warehouses like Snowflake, Databricks, BigQuery, Redshift, and more, enabling you to bring live analytics and visualizations from your data sources directly into Confluence pages.

The app provides a custom Sigma Analytics macro that you insert into Confluence pages to embed Sigma workbooks, workbook pages, workbook elements, data models, and reports. Simply type /sigma in any Confluence page editor, paste your Sigma embed URL into the macro configuration, and the app handles the rest - automatically detecting the embedding method and rendering the content on your page.

Sigma's powerful data connectivity means your embedded analytics stay synchronized with your source data, whether it's in Snowflake, Databricks, BigQuery, or other supported data warehouses. Teams can access up-to-date insights without switching between tools.

Public vs. Secure Embedding¶

The app supports both embedding methods offered by Sigma Computing. For comprehensive details, see the Sigma documentation Intro to embedded analytics.

Public Embedding: Best for Confluence pages accessible to external stakeholders or when you don't need user-specific permissions. No authentication required, and anyone who can view the Confluence page can see the embedded content.
Secure Embedding: Best for internal Confluence spaces with sensitive data where you need to control access based on user identity and Sigma team permissions. Users are authenticated via JWT-signed URLs, ensuring they only see content their Sigma teams can access. Email addresses must match exactly between Confluence and Sigma for authentication to work correctly.

Automatic Detection

Content authors simply paste Sigma embed URLs - the app automatically detects the embedding method and handles authentication if required. Note that secure embedding requires admin configuration first (see Step 2).

Step 1. Installation¶

Install Sigma Computing Embedded Analytics for Confluence from the Atlassian Marketplace on your Confluence instance.

Choose Your Path

If you only need public embedding, no additional configuration is required. Skip directly to Step 3. For secure embedding with authenticated user access, continue to Step 2 below.

Step 2. Configure secure embedding¶

Prerequisites¶

Before configuring secure embedding, ensure you have:

Confluence Admin permissions - Required to access the app settings from Confluence administration
Sigma Administration access - Required to generate client credentials, configure embedding settings, and retrieve Sigma teams when mapping Confluence groups

Step 2.1. Get Sigma client credentials¶

Log in to Sigma as an admin and navigate to Administration > Developer Access. Copy the API Base URL, then create a new Client ID and Secret. Ensure the credentials are scoped for both Embedding (JWT signing) and REST API access.

Tip

The secret appears only once in the "Access credentials" dialog. Write it down or keep the dialog open until you save it in the app settings (Step 2.3).

For a visual walkthrough, watch the video below:

For detailed instructions, see Generate embed client credentials in the Sigma documentation.

Step 2.2. Access app settings¶

Log in to Confluence as an admin, click the settings icon in the top-right corner, then navigate to Settings > Apps > Sigma Analytics in the left sidebar.

Step 2.3. Configure API credentials¶

In the Client Credentials section, enter your Sigma client credentials (API Base URL, Client ID, and Secret) and click Save Credentials.

Step 2.4. Configure user management¶

The app supports two modes for managing user access to embedded content. For detailed guidance on choosing between these modes, see Choose how to manage users in your secure embed in the Sigma documentation.

Manual User Management - Users must be pre-provisioned in Sigma before accessing embedded content. Best for strict access control.
Automatic User Management - User accounts are automatically created on first access and assigned to Sigma teams based on Confluence group memberships. Best for broad access without pre-provisioning.

Choose the configuration that matches your requirements and follow the corresponding instructions below.

Manual user management¶

In Sigma Administration, disable "Allow automatic embed user creation" under Administration > Embeds > Settings > User Creation.
In the User Management section of the app settings, select Manual User Management and click Save Configuration.
Provision user accounts in Sigma for each Confluence user who needs access. Email addresses must match exactly between Confluence and Sigma. See Manage access to a secure embed for detailed instructions.

Important

Users should log into Sigma directly at least once before accessing embedded content to ensure their accounts are fully provisioned.

Automatic user management¶

In Sigma Administration, navigate to Administration > Embeds and ensure "Allow automatic embed user creation" is enabled.
In the User Management section of the app settings, select Automatic User Management.
In the Team Assignments table below, map Confluence groups to Sigma teams. Click the dropdown in the last row and select a Confluence group - start typing to search if you have many groups. After selecting the group, a new row appears where you can choose one or more Sigma teams. Type to search and narrow down the team list. Click Save Configuration to apply your configuration.
(Optional) Configure a fallback team.

- When configured, users who don't match any group mappings are automatically assigned to this team, ensuring baseline access.

- When left blank or not configured, users without matching group mappings will have accounts created but won't be assigned to any team, preventing them from viewing content.

Understanding Team Assignment

Additive Only - Team memberships are never removed automatically. Remove users from teams in Sigma Administration.
5-Minute Cache - Configuration changes may take up to 5 minutes to take effect for users viewing Confluence pages with Sigma Analytics embeddings.
Multiple Groups - Users in multiple Confluence groups are added to all corresponding Sigma teams.
Internal Users - Existing Sigma internal users bypass automatic team assignment.

For concrete examples of how team assignments work in different scenarios, see Team Assignment Examples at the end of this guide.

Step 3. Get your embed URL from Sigma¶

For Public Embeds¶

Open the Sigma workbook you want to share. Click the down arrow next to the workbook name in the header, then select Share and export > Embedding.
Select the Public tab and choose the content you want to generate a public embed path for (Entire Workbook, Chart, or Table).
Copy the Public Link or Embed Code. The app supports both formats.

For Secure Embeds¶

The embed URL structure varies depending on what you're embedding. Here are common examples:

Workbook: https://app.sigmacomputing.com/your-org/workbook/WorkbookName-abc123
Element (chart or table): https://app.sigmacomputing.com/your-org/workbook/WorkbookName-abc123/element/xyz789
Report: https://app.sigmacomputing.com/your-org/report/ReportName-def456

For more details on URL structures and advanced configurations, see What URL to use in Sigma's documentation.

Most users would want to use Sigma's Embed Sandbox to help construct the embed URL. But that's not required, especially if you don't require customization and want to embed the entire workbook (not one of its elements). For example, the URL of the workbook can be copied directly from the address bar of your browser.

The below steps show how to find the URL of a workbook or its elements using Sigma's Embed Sandbox:

Open the Sigma workbook you want to share. Click the down arrow next to the workbook name in the header, then select Share and export > Embedding.
Select the JSON Web Token tab and choose the content you want to embed (Entire Workbook, Chart, or Table), then click Preview to open Embed Sandbox.
If you don't require additional customizations, simply copy the embed URL from the Workbook path field at the top of Embed Sandbox and proceed to Step 4.
(Optional) To configure and customize the embed, click Client Credentials and choose any credential you have access to, then click Load Embed. Configure additional options as needed, then click View URL to copy the secure embed URL.

Important

The client credentials used in Embed Sandbox don't have to match what's configured by your Confluence admin in the app settings.
Only URL parameters are honored when embedded in Confluence. JWT options like Assign new teams are ignored for security reasons and can only be configured by your Confluence admin via the app settings.
The JWT in the copied URL has already been used to load the sandbox preview and is no longer valid. The app will automatically generate a fresh JWT when the content is embedded in Confluence, so you can leave the expired JWT in the URL.

Step 4. Embed in Confluence¶

Create or edit a Confluence page. Type /sigma and select the Sigma Analytics macro from the dropdown menu.
Paste your embed URL (public or secure) into the macro configuration panel. The app automatically detects the embedding method based on the URL structure. If you wish, you can specify a fixed height for the embed.
Publish the page to view your embedded Sigma analytics. Congratulations on your first embedded Sigma Analytics macro in Confluence!

Troubleshooting¶

Content Not Loading¶

If embedded content is not loading or appears blank:

Verify the embed URL is correct and complete.
Check the browser console for errors.
Ensure the workbook is published in Sigma.
For public embeds, verify that public embedding is enabled for the workbook in Sigma.

Invalid Token Error¶

If you see an invalid token error when using secure embedding:

Verify that the correct API base URL, Client ID, and secret have been configured in the app settings.
Verify that the Client ID and secret have not been revoked. If they have, create and configure a new set of client credentials.

Access Denied or Permission Errors¶

If users see "You don't have permission to access this page" or permission errors and you are using manual user management, check for these possible causes:

Verify the user's email address in Confluence exactly matches their email in Sigma.
Verify the user has a provisioned account in Sigma with appropriate access.
Check that the user's Sigma teams have access to the workbook in Sigma Administration.

If you are using automatic user management, check for these possible causes:

Verify the user's email address in Confluence exactly matches their email in Sigma.
Check that the user's Confluence groups have team assignments or enable a fallback team.
Check that the mapped Sigma teams for the user's Confluence groups have access to the workbook in Sigma Administration.
Check if the user's email has already been provisioned as an internal user on Sigma without access to the workbook.
Ensure "Allow automatic embed user creation" is enabled in Sigma Administration.

Configuration Changes Not Taking Effect¶

Team calculations may be cached for up to 5 minutes. Wait 5 minutes for the cache to expire, then refresh the Confluence page.

User Not Assigned to Expected Teams¶

If users are not assigned to expected teams in automatic user management, check for these possible causes:

Verify the user is a member of the expected Confluence groups.
Check that group-to-team mappings are configured correctly in the app settings.
Ensure the Sigma teams exist and names match exactly (including capitalization and spacing).
If a Sigma team's name has recently been changed, go to team assignment and remap the team to the corresponding Confluence group.
Wait 5 minutes for caches to refresh if you just made configuration changes.
Check Sigma Administration to verify the user's actual team memberships.

Team Assignment Examples (Automatic User Management)¶

The examples below illustrate how automatic user management determines team assignments and content access based on your group-to-team mappings. These scenarios can help you understand how the configuration you set up in Step 2.4 translates into actual user access, and can be particularly useful when troubleshooting unexpected access issues.

The following examples assume this configuration:

Confluence Group	Sigma Team	Workbook Access
confluence-engineers	Engineering Team	✅ Yes
confluence-analysts	Data Analytics	✅ Yes
confluence-contractors	External Contractors	❌ No
confluence-marketing	(no mapping)	N/A
(fallback team)	General Viewers	✅ Yes

User Scenarios:

User	Confluence Groups	Assigned Teams	Can View?	Why
Alice	confluence-engineers	Engineering Team	✅ Yes	Matched group, team has access
Bob	confluence-engineers, confluence-analysts	Engineering Team, Data Analytics	✅ Yes	Multiple matched groups, both have access
Carol	confluence-marketing	General Viewers (fallback)	✅ Yes	No matching groups, fallback team has access
Dave	confluence-contractors	External Contractors	❌ No	Team assigned but lacks workbook permission
Eve	confluence-engineers, confluence-contractors	Engineering Team, External Contractors	✅ Yes	At least one team (Engineering) has access

References¶

Intro to embedded analytics, Sigma Documentation
Create and manage a public embed, Sigma Documentation
Create an embed API with JSON Web Tokens, Sigma Documentation
Manage access to a secure embed, Sigma Documentation
Generate embed client credentials, Sigma Documentation
Generate API client credentials, Sigma Documentation