Apache Superset Embedded SDK 实战利用 Guest Token 将仪表盘安全嵌入自有应用【免费下载链接】supersetApache Superset is a Data Visualization and Data Exploration Platform项目地址: https://gitcode.com/gh_mirrors/supers/superset本文围绕 Apache Superset 仓库中的 superset-embedded-sdk/README.md 展开讲解如何借助官方 Embedded SDK通过 iframe 将 Superset 仪表盘嵌入你自己的 Web 应用并使用 Guest Token 复用宿主应用自身的认证体系让用户无需登录 Superset 即可查看受控数据。读完本文你将掌握 SDK 的安装与调用、Guest Token 的签发原理、iframe 沙箱加固方式以及 SDK 底层的通信与令牌自动刷新机制。SDK 是什么一句话理解嵌入原理Embedded SDK 的核心思路非常简单在宿主页面中动态创建一个 iframe让 iframe 加载 Superset 内部的仪表盘页面从而把仪表盘“镶”进你自己的应用。SDK 负责三件关键事情根据传入的配置构造正确的嵌入式仪表盘 URL{supersetDomain}/embedded/{dashboardId}把宿主后端签发的 Guest Token 通过消息通道传递给 iframe 内的 Superset 页面完成免登录授权提供卸载、获取滚动尺寸、获取永久链接等控制能力方便宿主应用与嵌入式仪表盘交互。其核心实现位于 superset-embedded-sdk/src/index.ts 中的embedDashboard函数源码与本文后续内容一一对应。快速开始安装与最小调用通过 npm 安装SDK 以 npm 包形式发布包名为superset-ui/embedded-sdknpm install --save superset-ui/embedded-sdk安装后在代码中引入并调用import { embedDashboard } from superset-ui/embedded-sdk; embedDashboard({ id: abc123, // 由 Superset 的嵌入配置界面提供 supersetDomain: https://superset.example.com, mountPoint: document.getElementById(my-superset-container), // 任意可容纳 iframe 的 HTML 元素 fetchGuestToken: () fetchGuestTokenFromBackend(), dashboardUiConfig: { // 仪表盘 UI 配置hideTitle、hideTab、hideChartControls、filters.visible、filters.expanded可选、urlParams可选 hideTitle: true, filters: { expanded: true, }, urlParams: { foo: value1, bar: value2, // ... } }, // 可选额外的 iframe sandbox 属性 iframeSandboxExtras: [allow-top-navigation, allow-popups-to-escape-sandbox] });通过 CDN 加载也可以不经过构建工具直接从 CDN 加载。此时 SDK 会以全局变量supersetEmbeddedSdk暴露script srchttps://unpkg.com/superset-ui/embedded-sdk/script script supersetEmbeddedSdk.embedDashboard({ // ... 这里填入与上面示例完全相同的参数 }); /script说明SDK 当前仓库版本为0.1.0-alpha.12见 superset-embedded-sdk/package.json运行时依赖superset-ui/switchboardiframe 消息通信与jwt-decode解析 Guest Token 过期时间。embedDashboard 参数全解embedDashboard是 SDK 唯一的入口函数其类型定义EmbedDashboardParams位于 superset-embedded-sdk/src/index.ts各参数含义如下参数类型必填说明idstring是仪表盘的嵌入配置 ID由 Superset 的嵌入配置界面生成supersetDomainstring是Superset 实例域名需带协议如https://superset.example.commountPointHTMLElement是用于挂载 iframe 的宿主页面 HTML 元素fetchGuestToken() Promisestring是从宿主后端获取 Guest Token 的函数dashboardUiConfigUiConfigType否仪表盘 UI 与行为配置见下debugboolean否是否输出调试日志默认falseiframeTitlestring否iframe 的title属性默认Embedded DashboardiframeSandboxExtrasstring[]否额外的 iframe sandbox 属性默认[]dashboardUiConfig 详解dashboardUiConfig类型为UiConfigType见 src/index.ts控制嵌入后仪表盘的外观与交互字段类型说明hideTitleboolean隐藏仪表盘标题hideTabboolean隐藏 Tab 页签hideChartControlsboolean隐藏图表控制编辑类控件filters.visibleboolean是否显示筛选器面板filters.expandedboolean筛选器面板是否默认展开urlParamsRecordstring, any追加到嵌入式页面 URL 上的自定义查询参数从源码src/index.ts可以看到这些配置最终被序列化为 URL 查询参数传给 iframehideTitle、hideTab、hideChartControls通过位掩码合并为一个数字uiConfighideTitle记 1、hideTab记 2、hideChartControls记 8源码 src/index.tsfilters.visible与filters.expanded分别映射为 URL 参数show_filters与expand_filters映射表定义在 superset-embedded-sdk/src/const.ts若urlParams中的键与上述参数冲突urlParams优先生效见 src/index.ts 的合并顺序。认证与授权Guest Token 机制嵌入式资源使用一种特殊令牌 ——Guest Token访客令牌—— 来授予用户访问 Superset 的权限而无需你的用户直接登录 Superset。整体流程为宿主后端向 Superset 的POST /security/guest_token端点申请令牌再把令牌传给宿主前端前端 SDK 拿到令牌后用它完成仪表盘嵌入。在宿主后端创建 Guest Token宿主后端需要以 HTTPPOST方式请求/security/guest_token请求体描述该令牌将被授予哪些资源访问权限。Guest Token 还可以携带Row Level Security行级安全RLS规则按用户动态过滤数据。发起该请求的代理必须拥有can_grant_guest_token权限。服务端校验逻辑可在 superset/security/api.py 中查看请求体先经GuestTokenCreateSchema校验再校验资源存在性最后调用create_guest_access_token生成令牌。示例请求体{ user: { username: stan_lee, first_name: Stan, last_name: Lee }, resources: [{ type: dashboard, id: abc123 }], rls: [ { clause: publisher Nintendo } ] }字段说明与 superset/security/api.py 中的 schema 一一对应user可选用户属性可用于图表内的 Jinja 模板便于做个性化渲染对应UserSchema中的username、first_name、last_name字段resources必填令牌可访问的资源列表type目前支持dashboard枚举定义见 superset/security/guest_token.pyid为资源标识rls必填行级安全规则列表clause为过滤条件可选dataset指定数据集编号。令牌生效后的角色与默认配置在宿主应用内使用 Guest Token 时Superset 会创建一个匿名用户对象Anonymous user来完成认证。该访客匿名用户默认归属于公共角色对应配置项GUEST_ROLE_NAME Public该配置位于 superset/config.py。Guest Token 底层是 JWT相关的服务端配置也在 superset/config.py配置项默认值说明GUEST_TOKEN_JWT_SECRETtest-guest-secret-change-meJWT 签名密钥生产环境必须更换GUEST_TOKEN_JWT_ALGOHS256JWT 签名算法GUEST_TOKEN_JWT_EXP_SECONDS300令牌有效期默认 5 分钟GUEST_TOKEN_JWT_AUDIENCENoneJWT 受众声明可配置为固定字符串或回调函数启用嵌入式功能的特性开关嵌入功能默认并未开启。服务端需要打开特性开关EMBEDDED_SUPERSET默认False见 superset/config.py。嵌入式仪表盘的查询接口 superset/embedded/api.py 在before_request钩子中检查该开关未开启时直接返回 404。iframe 沙箱默认安全模型与扩展Embedded SDK 默认以sandbox沙箱模式创建 iframe对 iframe 内内容的执行施加限制。SDK 默认添加的 sandbox 属性见 src/index.ts包括allow-same-origin同源策略postMessage通信所必需allow-scripts允许执行脚本allow-presentation支持图表全屏展示allow-downloads支持将图表下载为图片allow-forms允许表单提交allow-popups支持将图表导出为 CSV 时打开弹窗。如需更多能力通过iframeSandboxExtras追加额外的 sandbox 属性例如放开顶层导航与弹窗逃逸iframeSandboxExtras: [allow-top-navigation, allow-popups-to-escape-sandbox]源码级剖析SDK 的底层工作机制1. 通信通道MessageChannel Switchboardiframe 加载完成后SDK 会创建一个MessageChannel把其中一个端口通过postMessage传给 iframe 内的 Superset 页面消息类型常量__embedded_comms__定义在 src/const.ts从而建立宿主窗口与 iframe 之间的双向通信参见 src/index.ts。Switchboard来自superset-ui/switchboard包在此基础上封装出类型安全的消息收发 APIGuest Token 正是通过这条通道发送给 iframe 内的仪表盘页面的。2. Guest Token 自动刷新Guest Token 默认有效期只有 5 分钟因此 SDK 会在令牌临近过期时自动重新调用fetchGuestToken并再次通过消息通道下发新令牌避免嵌入页面因令牌过期而请求失败。刷新时机的计算逻辑位于 superset-embedded-sdk/src/guestTokenRefresh.tsREFRESH_TIMING_BUFFER_MS 5000提前 5 秒刷新避免 Superset 请求恰好落在过期瞬间MIN_REFRESH_WAIT_MS 10000最小刷新间隔 10 秒防止异常场景下高频刷新请求DEFAULT_TOKEN_EXP_MS 300000当解析 JWT 的exp失败时按 5 分钟兜底计算。SDK 通过jwt-decode解析 JWT兼容整数秒与 ISO 字符串两种exp格式见 src/guestTokenRefresh.ts。对应的单元测试在 superset-embedded-sdk/src/guestTokenRefresh.test.ts覆盖了 epoch 秒、带小数的 epoch、ISO 日期、过期令牌与非法日期共五种场景。3. 返回的 EmbeddedDashboard 控制句柄embedDashboard返回一个 Promiseresolve 出的对象类型EmbeddedDashboard见 src/index.ts提供四个方法方法说明getScrollSize()获取 iframe 内容可滚动尺寸{ width, height }用于自适应宿主页面布局unmount()从mountPoint中移除 iframe卸载嵌入式仪表盘getDashboardPermalink(anchor)获取仪表盘指定位置的永久链接getActiveTabs()获取当前激活的 Tab 列表这四个方法都是通过 Switchboard 通道向 iframe 内的页面发起远程调用见 src/index.ts宿主应用可以据此实现“随仪表盘 Tab 切换而联动自身导航”“提供返回按钮时主动卸载”等产品化交互。端到端接入清单将以上内容串成一个完整的接入流程服务端打开特性开关EMBEDDED_SUPERSET True并设置生产环境的GUEST_TOKEN_JWT_SECRET权限为签发令牌的账号授予can_grant_guest_token权限并按需配置GUEST_ROLE_NAME对应的角色及其可访问资源宿主后端实现一个受你自身认证体系保护的接口内部调用POST /security/guest_token构造带user、resources、rls的请求体并返回令牌宿主前端安装superset-ui/embedded-sdk调用embedDashboard把fetchGuestToken指向第 3 步的接口并传入id、supersetDomain、mountPoint交互增强按需使用dashboardUiConfig定制 UI用iframeSandboxExtras调整沙箱策略用返回值中的四个方法实现卸载、滚动自适应、永久链接与 Tab 联动。总结Superset Embedded SDK 以“iframe 嵌入 Guest Token 授权 消息通道通信”三件套提供了一条将 Superset 仪表盘无缝接入自有产品体系的标准路径用户认证完全复用宿主应用数据访问通过resources与 RLS 规则精细收敛令牌自动刷新保证了长时间使用的稳定性沙箱默认策略则守住安全底线。若需更深入地调试或扩展建议直接阅读 superset-embedded-sdk/src/index.ts 与 superset/security/api.py 两份核心源码。【免费下载链接】supersetApache Superset is a Data Visualization and Data Exploration Platform项目地址: https://gitcode.com/gh_mirrors/supers/superset创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考