Why embedded Superset needs cookie, CSP and CORS settings
This page explains how to set SameSite and secure cookies, the frame-ancestors directive in the Content Security Policy, and CORS for your host origin so that Superset dashboards and charts load inside your own application. When a product team places Superset on a different origin from its app, the browser blocks the frame, the session cookie and the API calls by default. Each of those three blocks has to be lifted on purpose, and each setting widens what a third-party page can do with your users' sessions.
Superset is made of four components according to its architecture documentation: the Flask and React application, a metadata database, an optional caching layer, and optional Celery worker and beat processes. The browser-facing behavior that matters for embedding comes from the application itself, since it sets the session cookies, serves the pages that get framed and answers the API requests the embedded SDK makes. The metadata database, cache and workers do not talk to the browser, so their configuration does not solve a cross-origin failure.
Embedding is a cross-origin case by definition: the page that hosts the iframe and the Superset origin are different sites, so the browser treats the session as third-party context. Before changing any setting, confirm with your team which origins will host embedded content, whether they share a parent domain with Superset, and which browsers your users run. Those answers decide how much you need to loosen. Check the exact configuration keys against the version you deploy, because the configuration documentation is the reference for them.
Which browser settings to change for each embedding pattern
This table compares the session cookie attributes, the frame-ancestors directive in the Content Security Policy, and CORS origins with credentials for each embedding pattern. Read each row from the pattern to the settings, then check what each change loosens. The main takeaway is that cross-site embedding needs all three settings opened, and each opening should name the exact host origin. Confirm exact configuration key names against your Superset version.
| Embedding pattern | When it fits | Settings to change | What it loosens |
|---|---|---|---|
| Same-site subdomain | Host and Superset share a registrable domain, such as app.example.com and analytics.example.com. | Keep cookies Secure. Test SameSite Lax first. Name the host origin in frame-ancestors. Add CORS only if the host calls Superset APIs. | Little. Cookies stay first-party and framing is limited to one named origin. |
| Separate domain | A product on a customer or partner domain embeds dashboards served from your Superset domain. | Set the session cookie to SameSite None with Secure. List the host origin in frame-ancestors. Allow the host origin in CORS with credentials. | Cross-site cookies and cross-site framing. Each added host origin widens both. |
| Several host domains | One Superset instance serves dashboards to multiple customer or partner domains. | List each approved origin in frame-ancestors. List each origin in CORS and enable credentials only where a flow needs them. | Every listed origin can frame your dashboards and send authenticated requests to your APIs. |
| Public dashboard | A dashboard is published to anonymous viewers through the Public role. | Viewing needs no login cookie. Keep frame-ancestors limited to known hosts. CORS is usually not needed. | Anyone can view the published data. Framing limits still matter for clickjacking. |
| Local or staging testing | Embedding is tested on localhost or a staging host before production. | Secure cookies need HTTPS, so test with TLS enabled. Use the same origin list as production. | Development-only relaxations can reach production if they are not tracked in configuration. |
| Disabling framing protection | A quick fix when an embedded iframe shows blank or is refused. | Widen frame-ancestors to a wildcard or turn off the policy. Find the real cause in the origin list first. | Clickjacking protection for every page on the instance, not only the embedded dashboard. |
How to configure cookies, CSP and CORS for an embedded dashboard
This sequence sets the browser security controls so that a Superset dashboard loads inside your host page, the session cookies behave correctly across the embed, and only the approved host origin can call the Superset API. Each step ends with a check you can run before anything reaches production.
Confirm the host origin and parent domain
Write down the exact origin of every page that will embed Superset, including scheme, hostname and port, and the parent domain that the Superset and host applications share, if any. Your architect or product owner signs off on this list, because every later setting refers to it. Check that the list covers staging and production separately. The step is done when you have a short table of origins per environment that the whole team agrees on.
Serve Superset and the host over HTTPS
Confirm that Superset and every host page are served over HTTPS in the environment you are testing, with certificates issued for the hostnames in your origin list. Cookie attributes that browsers enforce for cross-site embedding depend on a secure connection, so a plain HTTP staging environment will not reproduce production behavior. The check is that the browser shows a valid certificate for both the host and the Superset URL, with no mixed content warnings in the developer tools console.
Set session cookie attributes for cross-site embedding
In the Superset configuration, set the session cookie attributes for embedded use, including the SameSite policy and the Secure flag, following the cookie settings in the Superset configuration documentation for the version you deploy. Confirm the exact configuration keys in that document, because names and defaults can change between releases. Your platform team applies the change through the same configuration path used for other settings. The check is that a login to Superset from the host context sets a cookie with the attributes you chose, visible in the Application tab of the developer tools.
Set frame-ancestors to the host origin only
Configure the Content Security Policy so that the frame-ancestors directive lists only the host origins from step one, and nothing broader. Avoid wildcards and avoid adding origins for convenience during testing, because a permissive list lets any site frame your dashboards. Confirm the header delivery method in the configuration documentation for your version, since the setting controls the response headers your proxy may also modify. The check is that the Content-Security-Policy response header on the Superset page contains exactly the approved origins, and that a test page on an unapproved origin is blocked from framing it.
Configure CORS for the host origin
Allow cross-origin requests only from the host origin list, for the endpoints the embedded SDK calls. Review the CORS settings in the Superset configuration documentation for your version to find the correct keys and the allowed methods and headers they accept. Keep credentials handling consistent with the cookie choices from step three, because browsers refuse credentialed requests when the origin is wildcarded. The check is that a preflight request from an approved origin receives the expected Access-Control-Allow-Origin value, and that a request from an unapproved origin receives no matching header.
Test the embed in staging with browser developer tools
Load a test host page that embeds one dashboard, then open the browser developer tools and watch the Network and Console panels during login, guest token exchange and filter changes. Look for blocked frames, refused cookies, failed preflight requests and CSP violation reports. Repeat the test in a private window, in a second browser, and from a page on an origin you have not approved, to confirm the negative case. The step is complete when the embed works for approved origins, every console violation is explained and resolved, and the unapproved origin is blocked.
Record the settings and retest after each upgrade
Save the final cookie, CSP and CORS values with the deployed Superset version in your configuration repository, and attach the test results from step six. Before any Superset upgrade, reread the configuration documentation for the target version, since these settings can move or change meaning, and repeat the browser checks in staging. The record is done when a colleague can reproduce each check from the document alone and the staging test is scheduled as part of the upgrade plan.
Why loosening these settings opens data exposure risk
Cookies, CSP and CORS are the settings that decide which sites can frame Superset, which origins can call its API with a user's session, and what an anonymous or guest viewer can reach. Each one is often loosened to make an embed work, and each loosening widens what an attacker or an unintended viewer can see. The cards below pair each risk with the control to review before go-live.
Wildcard frame ancestors enable clickjacking
A frame-ancestors value of * or an overly broad host list lets any site place Superset inside its own page. An attacker can overlay hidden controls on top of a logged-in dashboard and trick a user into clicks they did not intend. Review the frame-ancestors directive in the Content Security Policy and list only the exact host origins that embed your dashboards, including staging hosts you actually use.
Credentialed CORS with broad origins
When CORS allows credentials, the browser sends session cookies with cross-origin API calls, and the response is readable by the calling page. If the allowed origin list is broad, any site a logged-in user visits can read API responses that contain dashboard or dataset data. Review the allowed origins in your Superset configuration and confirm that each one is a host you own and trust, with no wildcard combined with credentials.
SameSite None without Secure
Embedding in a third-party iframe often requires SameSite=None on the session cookie, and browsers reject that setting unless the cookie is also marked Secure. Omitting Secure either breaks the embed or pushes teams to weaken other settings to compensate. Confirm that cookies are sent only over HTTPS, that the Secure flag is set in every environment that serves embeds, and that no plain HTTP path exists for the login flow.
Public and guest access widen iframe reach
A public dashboard or a guest token grants access without a named user login, so the iframe can display whatever that role or token can query. Broad dataset grants for the public role or a guest token without row level security can expose rows that belong to other customers. Before embedding, review which datasets the public role and guest tokens can read, and test that a viewer with one tenant's token cannot see another tenant's data.
Loosened settings persist after the fix
Teams often widen CSP, CORS or cookie settings during an integration sprint and never tighten them again. Each change made to unblock one embed remains in effect for every dashboard and every user, which makes the final configuration harder to audit. Keep the settings in version-controlled configuration, record the reason for each relaxed value, and review the list at each upgrade or new embed request.
How the settings differ across production, staging and local testing
Production is where the embedding settings carry real risk, because cookies, frame rules and cross-origin requests all decide whether a customer session can be used to read data it should not see. Production should serve Superset and the host application over HTTPS, with a single, explicitly listed host origin allowed to frame dashboards and call the API. Treat every other origin as unknown until someone approves it in writing.
- Explicit origins only: List the host application's exact origin in the frame-ancestors directive and CORS allow list, with no wildcards.
- Secure cookies: Session and CSRF cookies should be marked Secure so browsers send them only over HTTPS.
- Deliberate SameSite value: Confirm the SameSite value your embedding flow needs in your browser tests, and document why it was chosen.
- No debug flags: Confirm that no development-only switch, permissive header or test certificate exception has reached the production configuration.
- Reviewed changes: Route every change to these settings through the same review and change record as other security configuration.
Before go-live, check the live response headers from the production URL in each browser you support, not only the configuration file.
Staging exists to catch browser behavior that only appears under production conditions. The most useful staging setup mirrors production's origins, scheme and proxy path, so that the same frame and cookie rules are exercised before release. A staging host on a different domain or without HTTPS will pass tests that production later fails, or the reverse.
- Matching origin shape: Use the same scheme, host pattern and reverse proxy chain as production, with only the hostname changed to a staging name.
- Separate allow lists: Staging origins belong in staging's own configuration. Do not add staging origins to production to make a test pass.
- Same cookie attributes: Run staging with the same Secure and SameSite settings as production, so cookie failures appear before release.
- Header inspection: Compare the response headers from staging and production after each deployment and record any difference.
- Test accounts only: Use synthetic data and test tenants in staging, and confirm that no production data was copied in during setup.
The item to confirm is whether your staging hostnames, TLS setup and proxy headers match production closely enough that a passing test would also pass in production.
Local development is where teams are most tempted to relax settings. Plain HTTP on localhost, a self-signed certificate and broad origin allowances make the embedding flow easy to start, but they hide the failures that appear in production. Developers should be able to work quickly without changing the rules that production depends on.
- Relaxed settings stay local: Permissive headers, disabled certificate checks and wildcard origins are acceptable only on a developer machine and must not be committed to shared configuration.
- Separate configuration file: Keep development overrides in a local file excluded from version control, so they cannot be deployed by accident.
- Known differences: Write down which settings differ from production, such as HTTP versus HTTPS, so testers know which results to trust.
- Frequent production-like checks: Run a build against a production-like configuration before merging, instead of relying only on local results.
- Never copied forward: Do not copy local overrides, sample keys or development origins into staging or production.
The item to confirm is that your repository and deployment pipeline reject development-only values, and that the team can name each setting that differs from production.
Questions teams ask before configuring embedded Superset security
How much effort does configuring embedded Superset security take?
The effort depends on how many host origins embed dashboards, how many environments must agree on the same settings, and how much of the host application's routing and login flow sits inside a different domain. Cookie settings, the frame-ancestors directive and CORS origins are each small configuration changes, but each one has to match what the browser actually sends in a live embed. Teams with one host origin on the same parent domain usually find the work is mostly verification. Teams with several origins, custom subdomains or a single sign-on redirect in the middle need more design time and more browser testing. Ask any partner to size the work from a written list of origins, environments and login paths.
Can our internal team configure these settings without a partner?
Yes, if the team has someone who understands Flask session cookies, browser cookie rules and HTTP response headers, and who can test in a real browser across the host application's domains. The settings live in Superset's configuration file, and the work is well bounded. The risk is in loosening them: a team that sets SameSite to None, widens frame-ancestors or allows wildcard CORS origins without a clear reason can create an exposure that is hard to see in normal use. A partner is most useful as a second reviewer who checks the final policy against the embed flows, documents the decisions and tests that other users cannot read data through a permissive setting.
What does the work need from the host application team and the platform team?
The host application team must list every page that embeds Superset, the domains those pages run on, how users sign in, and whether the embed uses the embedded SDK from the browser. They also need to confirm how the guest token request reaches the backend, because that request determines which origins need CORS access. The platform team must control the Superset configuration, the reverse proxy or ingress that sets headers, the domain and TLS setup, and the environments where changes are tested. Both teams should agree on a single source of truth for allowed origins, because a mismatch between the proxy and the application configuration is a common cause of failed embeds.
How long does browser testing take as the number of origins grows?
Testing time grows with the number of origins, the number of browsers you support and the number of login paths, not with the size of the dashboard. Each origin needs a check that the embed loads, that the session cookie is sent where required, that CORS preflight requests succeed and that the browser blocks the embed from any origin that is not listed. Single sign-on flows add cases because redirects can change the cookie context. Ask for the test matrix in writing before work starts, including which browsers, which environments and which negative tests are included. The duration is set by that matrix and by how many fix cycles the team expects, so no fixed figure applies across deployments.
What should we ask for in a quote for this configuration work?
Ask for a written scope that names each host origin, each embedded dashboard or chart, each environment, the Superset version and the browsers in the test matrix. The quote should list what is planned for the cookie, frame-ancestors and CORS settings, how the reverse proxy headers will be verified and what evidence will be delivered, such as configuration files, test results and a short record of each decision to loosen a setting. Ask which items are one-time and which recur, for example, re-testing after each Superset upgrade or a new host origin. DeployOpen does not publish a price list, and a quote follows from that written scope.
What happens when the host app or the Superset version changes?
Both changes can break an embed. A new host domain or subdomain requires a new frame-ancestors entry and possibly a new CORS origin, and a change to the login provider can change how the session cookie is set. A Superset upgrade can change how headers, cookies and the embedded SDK behave, so the upgrade guide and the release notes for the version you move to should be checked before the change. The Superset upgrade documentation says to back up the metadata database, run superset db upgrade and superset init, test in staging first and check UPDATING.md for breaking changes. Plan a regression run of the embed test matrix as part of every upgrade and every new origin, and budget for that recurring work.
What to confirm in your environment before going live
Browser security settings for embedding depend on several layers at once: the Superset release you run, the proxy in front of it, the browsers your users choose and the sign-in flow your identity provider uses. The cards below list what to verify in each layer, because a setting that works in staging can fail for a real user on a different browser or path.
Exact configuration keys and defaults
Cookie, header and CORS settings are defined in the configuration file, and the names and default values can change between Superset releases. Confirm the keys for your exact version against its configuration documentation, then record the effective values from the running container, not from a template copied from an older deployment. Treat any value you cannot trace to a documented key as unverified until it is tested.
Reverse proxy and load balancer headers
Many embedding problems come from the layer in front of Superset. A proxy can add, strip or override Content-Security-Policy, Set-Cookie and Access-Control-Allow-Origin headers, and a load balancer can terminate TLS so Superset sees plain HTTP. Ask the platform team which component sets each header, whether it is set once or by both layers, and capture the response headers on each route the host page uses.
SameSite behavior across user browsers
Cookie handling for cross-site iframes changes with browser versions and with the SameSite and Secure attributes. Build a short matrix of the browsers and versions your users run, including managed enterprise builds, and test login, token refresh and dashboard load inside the host page in each one. Do not assume that a single modern browser represents the rest of your user base.
Cross-site redirects in the identity flow
If sign-in sends users through a separate identity domain and back, the redirect chain may depend on cookies that browsers treat as cross-site inside an embedded frame. Map every redirect from the host page to the identity provider and back to Superset, noting which domain sets each cookie. Where the flow crosses sites, plan for a top-level sign-in step or a token exchange done by your backend, and confirm that choice with your identity team.
Kubernetes packaging path
The Helm chart referenced in the 6.1.0 documentation is marked deprecated in current development docs, which points new deployments to the Kubernetes operator. The operator is in alpha with a v1alpha1 API whose schemas may change between releases. Decide which packaging path you will run, confirm how header and cookie settings are passed through it, and plan for how you will re-apply those settings during an upgrade.
How upgrades and the Kubernetes operator affect these settings
Header and cookie behavior can change between Superset releases, so the cookie attributes, frame-ancestors directive and CORS rules you verified on one version are not guaranteed to hold on the next. Treat each upgrade as a change to the embedding surface, not only to the application. The upgrade guide asks you to back up the metadata database, run superset db upgrade and superset init, and test in staging before production. Before you start, read UPDATING.md for the target version and look for entries that touch authentication, session handling, talisman or other header settings, and CORS. Those entries decide which parts of your test plan have to be repeated.
Your staging test for embedding should load the host page in a real browser against the upgraded instance, then confirm that the dashboard renders in the iframe, that the guest token flow still sets or accepts the session it needs, and that the browser console reports no frame-ancestors or cross-origin errors. Check the response headers directly with curl, not only through the browser, so you can compare them with the values you recorded before the change. Confirm the current status of the Helm chart and the operator in the documentation for the version you plan to run, because the Kubernetes installation guide and the operator documentation may differ.
The current development docs mark the Helm chart as deprecated and point new deployments to the Apache Superset Kubernetes Operator, which is in alpha with a v1alpha1 API whose schemas may change between releases. Ingress annotations, proxy headers, and any values that set SESSION_COOKIE_SAMESITE, TALISMAN_CONFIG, or ENABLE_CORS should live in version-controlled manifests or config files, not in a cluster edited by hand. Reapply them through the same pipeline after every change, then rerun the embedding checks. Ask any vendor or integrator you engage to show where these settings are stored and how they are retested after an operator upgrade.
Security checks that keep embedding safe over time
Browser security settings for embedding tend to drift. A release changes a default, a new host domain gets added in a hurry, or a rotated secret breaks sessions in a way nobody traces back to the header change. The checks below keep frame-ancestors, CORS and cookie behavior under test and under review after every change that touches them.
Regression test frame-ancestors and CORS
Add a pipeline test that loads the embedded dashboard from each approved host origin and confirms the response carries the expected frame-ancestors directive and CORS headers. The same test should confirm that an origin outside the list is refused. Run it against staging after every configuration change, not only after Superset upgrades, because a proxy or ingress edit can strip or duplicate headers without touching Superset itself.
Review allowed origins on a schedule
Each host domain that appears in frame-ancestors or the CORS allow list is a trust decision. Keep a dated register of every origin, its owner and the product that uses it, and review the list on a set cadence set by your security policy. Remove origins for retired products and test subdomains first. Ask your team who can request a new origin and what evidence they must provide before the change is merged.
Handle SECRET_KEY rotation carefully
Superset requires a user-specified SECRET_KEY to start, and it signs the session cookies that embedded users depend on. Store the key in your secrets manager, not in a checked-in config file. When rotating, set PREVIOUS_SECRET_KEY to the old value so existing sessions remain valid during the transition, then remove it once the rotation window closes. Test the rotation in staging so that a rotation does not look like a cookie or CSP fault.
Log rejected cross-origin requests
When the browser blocks a framed request or a CORS call, the failure appears only in the user's console, so operators see a support ticket instead of a signal. Forward the reverse proxy and Superset application logs to your central log platform and alert on spikes of 403 or CORS-related responses from the embedding paths. A sudden rise often points to a host that changed its domain or an attempt to embed the dashboard somewhere it was never approved.
Re-test after every Superset upgrade
Treat each Superset upgrade as a review point for the browser security settings. Check the upgrade notes for changes to cookie, header or session behavior, then run the regression tests and a manual embed check from each approved origin in staging. Confirm the upgrade procedure has not reset any custom settings. Keep the results with the change record so an auditor can see that the controls were verified after the change.
Confirm cookie flags in each environment
The SameSite and Secure settings that work in a local test often differ from production, where TLS terminates at a load balancer and the embedding host sits on another site. Verify the actual Set-Cookie attributes in every environment with a browser or HTTP client, not only in configuration files. Ask your platform team to document any proxy rule that rewrites cookie attributes, because an undocumented rewrite is one of the most common reasons embedding works in staging and fails in production.
