[SIP-75] Proposal for Embeddable Dashboards

[SIP-75] Proposal for Embeddable Dashboards

📣 Status

Currently in alpha and under active development. You can activate the feature by turning on the EMBEDDED_SUPERSET feature flag. Embed dashboards into your application using the @superset-ui/embedded-sdk package on npm.

It is not advised to use this feature in production at this time! This will be subject to breaking changes from future PRs, and currently lacks important user-facing functionality.

As we continue development, relevant PRs will mention this issue, and be linked automatically by GitHub below. Check back with this page to stay up-to-date with progress. (you can also subscribe in the issue sidebar)

Motivation

Embedding Superset dashboards into a third-party application is currently only possible if the dashboard is made public, or if users authenticate through Superset. We would like to add a feature to integrate dashboards into third-party applications (“Host Apps”) with authentication handled by the Host App.

There should be no need to log in to an integrated dashboard if the user is already logged in to the Host App.

Example use cases:

• A storefront wants to offer engagement metrics to each of its vendors, integrated into the store management experience.
• A bank wants to offer a curated financial wellness dashboard to account holders.

Superset currently allows for a variety of valid strategies for granting API access, which can include various types of API Keys, depending on the deployment. Rather than force a specific API Key system into Superset, we’ve designed this spec to be agnostic to those details and depend on the existing security manager features as much as possible.

Proposed Change

1. Dashboard creator marks their dashboard as “embedded” in the dashboard UI. This design isn’t done yet, but it’ll likely be a modal or a new panel in the edit mode sidebar. Dashboard creator defines a list of allowed referrer domains. When a creator makes a dashboard embedded, documentation is displayed on how to actually embed the dashboard.

2. Introduce a new endpoint POST /embedded-resource/, which returns an Embed Token that can be used to view the embedded resource. This token will be a JWT containing user info, row-level-security parameters (could be encoded either as a filter expression or as a RLS rule id), and grants of access to certain dashboards. It expires fairly quickly, so it must be refreshed periodically.

3. A Superset SDK is available for the Host App frontend to use, which will render the embedded dashboard page in an iframe, and pass the Embed Token through to the iframe using postMessage. The Host App will pass a function to the SDK which fetches a new Embed Token, so when the token is about to expire, the SDK can get a new one.

4. A new page, /embed/dashboard/:id will be used as the url for the iframe. This page acts as a wrapper around the dashboard. It receives the message from Host App containing the Embed Token, validates the sender of the message, and ensures that all requests use the token as auth.

5. When a request is made using an Embed Token, security manager will use the information in the token to do its checks rather than looking up user, role and RLS info from the database.

Sequence diagram of the embedded dashboard auth flow:

New or Changed Public Interfaces

POST /embedded-resource/ endpoint

A new frontend SDK that will expose functions to embed a dashboard into the Host App

New dependencies

flask-jwt-extended for handling jwt embed tokens

Migration Plan and Compatibility

Will create new table embedded_dashboards containing a dashboard id reference, an allowlist of referrers, and any additional configurations of the embedded dashboard

Rejected Alternatives

OAuth login - requires users to sign in to the iframe, lower UX Generating a url or token in the Host App - better to keep generation on Superset side to avoid exposing implementation details, and so that we don’t have to define a specific API key spec Passing a signed url instead of an embed token - This makes revoking access more complex

[michael-s-molina]

@suddjian Thanks for writing this SIP. I have some broad questions to help with the SIP definition/scope:

Do we have any plans to support cross-window communication? One common requirement is to allow interactions in the host app to impact the embedded dashboard or the other way around. Some examples:

• The host app already has a filter bar and wishes to apply these filters to the dashboard
• A user selects a slice of a pie chart and the host app shows a detailed report about the data

Are we going to provide any sort of client/toolkit to our users to help with the embedding process?

How are we going to handle URL and JWT expiration? Are we going to have specific endpoints for that?

Should we also add a “How to Embed Superset” wiki page as one of the deliverables of this SIP?

[gokhansari]

Thank you @suddjian for the proposal and your commits. It’ll be life saver. There is one thing that I would like to mention before you guys finalizing this feature.

Custom Url Parameters feature is one of the handy functionalities and It is not dispensable. When I check the master branch, for now It seems Embedded SDK only takes dashboardID parameter. To be able to use {{ url_param('custom_variable') }} and reference It in dataset SQL queries, I think there should be an other SDK parameter like url_params: string as we all used to use a lot of url parameters.

Example from doc:

www.example.com/superset/sqllab?countrycode=ES&language=EN

SELECT count(*)
FROM ORDERS
WHERE country_code = '{{ url_param('countrycode') }}' AND language_code = '{{ url_param('language') }}'