Embedded Dashboard Rendering#

Overview#

Superset's embedding infrastructure lets external applications render dashboards inside iframes without requiring end-users to have Superset accounts. The feature is gated by the EMBEDDED_SUPERSET feature flag (default: False); enabling it unlocks the /embedded/<uuid> route, the REST API, and guest-token issuance.

Key Components#

1. EmbeddedDashboard Model#

superset/models/embedded_dashboard.py defines the embedded_dashboards table with three meaningful columns:

The allowed_domains property splits the raw string into a list. An empty list means any origin can embed the dashboard.

2. Server-Side Route: /embedded/<uuid>#

superset/embedded/view.py — EmbeddedView.embedded() — handles the page load:

1. Aborts with 404 if EMBEDDED_SUPERSET is disabled 1.
2. Looks up the EmbeddedDashboard record by UUID; aborts 404 if not found 2.
3. Validates the request Referer header against allowed_domains; aborts 403 on mismatch 3.
4. Logs in an AnonymousUserMixin for the request scope, then renders superset/spa.html with the embedded JS entry point 4.

The bootstrap payload passes GUEST_TOKEN_HEADER_NAME and the resolved dashboard_id to the frontend 5.

3. Guest Token Authentication#

The host application backend calls POST /api/v1/security/guest_token/ to obtain a short-lived JWT. The default expiry is 300 seconds (5 minutes), configured via GUEST_TOKEN_JWT_EXP_SECONDS 6. The token payload carries:

• A synthetic user identity (username, first_name, last_name)
• A resources list (dashboard UUIDs the token grants access to)
• Per-dataset RLS rls rules ({ "clause": "...", "dataset": <id> })

On every API request the backend resolves the X-GuestToken header 7 to a transient GuestUser. has_guest_access() checks that the requested dashboard UUID is in the token's resource list 7.

RLS clauses from the token are injected as SQL WHERE filters during query execution 8. Omitting the dataset field applies the clause globally to all datasets the token touches — always scope RLS rules with dataset in multi-datasource dashboards 8.

4. Embedded SDK (@superset-ui/embedded-sdk)#

The superset-embedded-sdk package (v0.2.0) is the official host-app integration point. Its single exported function, embedDashboard(), accepts:

• id — the embed configuration UUID
• supersetDomain — e.g. https://superset.example.com
• mountPoint — DOM element to inject the iframe into
• fetchGuestToken — callback that your backend calls to return a fresh guest token
• dashboardUiConfig — optional UiConfigType for UI chrome control

The SDK mounts an iframe pointed at /embedded/<id> 9, establishes a MessageChannel for bidirectional comms via @superset-ui/switchboard 10, and auto-refreshes the guest token before expiry 11.

The UiConfigType controls UI chrome via a bitmask passed as a uiConfig URL param 12:

The SDK also exposes methods on the returned EmbeddedDashboard handle: getScrollSize, getDashboardPermalink, getActiveTabs, observeDataMask, getDataMask, and setThemeConfig 13.

5. Standalone URL Parameter#

Independent of the SDK, any Superset dashboard URL supports a ?standalone=<n> query parameter to strip chrome for minimal embedding or screenshot use. Values come from the DashboardStandaloneMode enum:

The standalone param is classified as a reserved URL parameter and is excluded from dashboard filter params 14.

Request Flow#

Configuration Checklist#

For CSP configuration, add a frame-ancestors directive to TALISMAN_CONFIG 15.

Key Source Files#