Superset Embedded SDK

[sainikhilsamineni]

@dosu can you tell me the use of embedde sdk and how to use it ?

[dosubot[bot]]

The Superset Embedded SDK lets you securely embed Superset dashboards into your own web applications, typically using an iframe. It's designed for scenarios where you want users to view analytics inside your app without logging directly into Superset, and is the only officially supported method for embedding dashboards when using OAuth/SSO setups source.

How to use it:

1. Prerequisites:

   • Enable the EMBEDDED_SUPERSET feature flag in Superset.
   • Set a strong password for GUEST_TOKEN_JWT_SECRET in your Superset config.
   • Make sure your dashboard is published and configured for embedding, and your embedding domain is allowed in Superset's settings source.

2. Install the SDK:

   • With npm:
     npm install --save @superset-ui/embedded-sdk
   • Or load from CDN:
     <script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>

3. Backend setup:

   • You need an API endpoint in your backend to generate a guest token (JWT), signed with the same secret as Superset. Superset does not generate these tokens for you.
   • Example (Node.js/Next.js):

     import jwt from "jsonwebtoken";
     export default function handler(req, res) {
       const payload = {
         user: { username: "viewer" },
         resources: [{ type: "dashboard", id: "<dashboard_id>" }],
         rls: [],
         type: "guest",
         aud: "superset",
       };
       const token = jwt.sign(
         payload,
         process.env.SUPERSET_SECRET, // Same as GUEST_TOKEN_JWT_SECRET
         { algorithm: "HS256", expiresIn: "10m" }
       );
       res.status(200).send(token);
     }

   • Your frontend fetches this token and passes it to the SDK source.

4. Embed the dashboard:

   • Example usage:

     import { embedDashboard } from "@superset-ui/embedded-sdk";
     embedDashboard({
       id: "abc123", // dashboard id
       supersetDomain: "https://superset.example.com",
       mountPoint: document.getElementById("my-superset-container"),
       fetchGuestToken: () => fetch("/api/superset-token").then(res => res.text()),
       dashboardUiConfig: { hideTitle: true, filters: { expanded: true } },
       iframeSandboxExtras: ['allow-top-navigation'],
       referrerPolicy: "same-origin"
     });

   • You can customize the embedded dashboard's UI (hide title, tabs, controls, filters), pass URL params, and configure iframe sandbox and referrer policy source.

5. Advanced features:

   • The SDK provides an API for programmatic interaction (get active tabs, chart states, data masks, chart data payloads, set theme config/mode).
   • You can customize permalink URLs generated inside embedded dashboards using the resolvePermalinkUrl callback source.

Troubleshooting:

• Make sure your guest token includes the correct dashboard id, is signed with the right secret/audience, and hasn't expired.
• Configure CORS, X-Frame-Options, and allowed_domains properly in Superset.
• If you see a 403 error, double-check all config steps and permissions source.

For full details and code samples, check the official README.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[sainikhilsamineni]

@dosu I'm using default db auth for now. i have tenant wise roles and access to set of dashboards corresponding to these roles. is it possible to provide guest token to that particular role ?

[dosubot[bot]]

Guest tokens in Superset Embedded SDK don't map directly to tenant-wise roles. Instead, you control access by specifying which dashboards (and optional row-level security rules) are included in the guest token payload. When a guest token is used, Superset creates an anonymous user assigned to the role set by GUEST_ROLE_NAME (default is "Public"), not your custom tenant roles.

To implement tenant-wise access, generate guest tokens that only include the dashboards and RLS rules appropriate for each tenant. You can also add custom user attributes (like tenant_id) to the token, which can be used in Jinja templates or RLS clauses for fine-grained filtering. If you need to enforce that tokens always include tenant-specific restrictions, use the GUEST_TOKEN_VALIDATOR_HOOK config to validate token payloads before they're issued see details, API details, custom attributes example.

So, guest tokens let you implement tenant-based access, but you do it by controlling the dashboards and RLS rules in the token—not by mapping to Superset roles.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[LiamTorrelli]

Short version of what the embedded SDK actually does, and then the tenant-role question — because that's the part that trips people up.

What it's for

@superset-ui/embedded-sdk mounts a Superset dashboard in a cross-origin <iframe> inside your app. The user never logs into Superset directly. Your backend mints a short-lived guest JWT, the SDK passes it over postMessage, and Superset spins up an anonymous session inside the frame.

Superset does not hand guest tokens to the browser. Your app calls /api/v1/security/guest_token/ server-to-server (with a privileged service account), gets the JWT back, and your fetchGuestToken callback returns it to the client.

Minimal client side:

import { embedDashboard } from "@superset-ui/embedded-sdk";

embedDashboard({
  id: "<dashboard-uuid-from-embed-modal>",
  supersetDomain: "https://superset.example.com",
  mountPoint: document.getElementById("analytics-container"),
  fetchGuestToken: () =>
    fetch("/api/superset-guest-token").then((r) => r.text()),
  dashboardUiConfig: { hideTitle: true },
});

Server side you POST something like:

{
  "user": { "username": "tenant_acme_viewer" },
  "resources": [{ "type": "dashboard", "id": "<uuid>" }],
  "rls": [{ "clause": "tenant_id = 'acme'" }]
}

Signed with GUEST_TOKEN_JWT_SECRET. Default expiry is 300 seconds.

Your tenant-role question

No — a guest token does not map to your existing tenant FAB roles the way normal DB auth does.

Every guest session gets whatever role GUEST_ROLE_NAME points at (default Public, a lot of teams bump it to Gamma when charts come back empty). Your per-tenant roles in Superset are bypassed for the iframe session.

Multi-tenant access is enforced in your token-minting code, not by picking a Superset role:

1. User logs into your app (DB auth, SSO, whatever).
2. Your backend resolves tenant → allowed dashboard UUIDs for that tenant.
3. You mint a guest token whose resources list only includes those dashboards, and whose rls clauses scope the SQL (e.g. organization_id = 123).
4. Optional: GUEST_TOKEN_VALIDATOR_HOOK in superset_config.py to reject tokens that arrive without tenant scoping.

So tenant A never gets tenant B's dashboards because your API never puts them in the payload — not because Superset evaluated their FAB role inside the iframe.

The trap: treating the guest token as "extend my logged-in user into Superset." It's a second auth system. Your app's session and the iframe JWT are parallel. RLS in the token is synthetic — whatever string your backend injects gets compiled into every query. Stale or missing clauses leak data even when the UI looks fine.

Before it works at all

EMBEDDED_SUPERSET = True, rotate GUEST_TOKEN_JWT_SECRET, CORS + Talisman/frame-ancestors, and add your parent origin in the dashboard Embed modal Allowed Domains. Missing any of those and you'll debug iframe errors before you ever get to tenant logic.

We wrote up the full flow — embedDashboard() lifecycle, postMessage handshake, RLS, and all nine server switches: https://www.drafted.work/blog/superset-embedded-sdk-guest-tokens