Metabase Embedding SDK 的 Guest 认证配置详解MetabaseIsGuestAuthConfig 类型实战指南【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读在 Metabase 的 Embedding SDK 中MetabaseIsGuestAuthConfig是声明 Guest Embed访客嵌入 模式的核心类型它告诉 SDK 以访客身份加载嵌入的仪表盘或问题无需为每个终端用户创建 Metabase 账号、无需接入 SSO。本文基于 SDK 的公开类型定义与开源仓库源码完整讲解该类型的字段语义、与其他认证方式API Key / JWT / SAML的互斥关系、guestEmbedProviderUri的 JWT 获取与刷新机制并给出可直接落地的配置示例与源码级原理分析帮助你正确、安全地在应用中接入 Guest 嵌入。类型定义一探 MetabaseIsGuestAuthConfig 全貌官方类型声明根据 MetabaseIsGuestAuthConfig.md 的类型片段该类型在 SDK 中定义如下type MetabaseIsGuestAuthConfig { metabaseInstanceUrl: string; } { apiKey?: never; fetchRequestToken?: never; guestEmbedProviderUri?: string; isGuest: true; preferredAuthMethod?: never; };字段语义逐项拆解名称类型说明metabaseInstanceUrlstring必填。你的 Metabase 实例的基础 URL例如https://metabase.example.com。SDK 会基于该地址发起嵌入请求。isGuesttrue必填。将值固定为true声明 SDK 应工作在Guest Embed 模式访客嵌入模式下。guestEmbedProviderUri?string可选。用于获取和刷新访客嵌入 JWT 令牌的 URL 端点仅 iframe 嵌入场景有效不适用于 SDK 原生 Guest 模式。既支持令牌过期时的刷新也支持在未提供静态令牌时于首次加载时获取令牌。两种情况下均作用于访客嵌入组件metabase-dashboard与metabase-question。端点应返回形如{ jwt: string }的新令牌。apiKey?never禁止出现。Guest 模式下不得使用 API Key 认证。fetchRequestToken?never禁止出现。Guest 模式下不得自定义令牌获取函数该函数属于 JWT SSO 场景。preferredAuthMethod?never禁止出现。Guest 模式下无需指定偏好的认证方式该字段用于 SAML/JWT 并存时的选择。never类型的含义是如果配置对象中出现了这些字段TypeScript 类型检查将直接报错。这是 SDK 通过类型层面的互斥约束保证四种认证模式API Key / JWT / SAML / Guest在同一配置对象中不会相互混淆。源码中的完整定义仓库中该类型的真实实现位于 frontend/src/embedding-sdk-shared/types/auth-config.tsMetabaseIsGuestAuthConfig定义在 L64-L81。与文档片段相比源码中保留了完整的 JSDoc 注释并通过类型组合清晰地展示了继承关系type BaseMetabaseAuthConfig { metabaseInstanceUrl: string; }; export type MetabaseIsGuestAuthConfig BaseMetabaseAuthConfig { isGuest: true; guestEmbedProviderUri?: string; apiKey?: never; preferredAuthMethod?: never; fetchRequestToken?: never; };可见metabaseInstanceUrl是所有认证配置的公共基础字段而isGuest: true是 Guest 模式区别于其他模式的判别标志。四种认证方式的联合类型与互斥关系MetabaseIsGuestAuthConfig只是 SDK 认证配置的一个分支。完整的认证配置类型MetabaseAuthConfig是一个可辨识联合discriminated union见 MetabaseAuthConfig.mdtype MetabaseAuthConfig | MetabaseAuthConfigWithApiKey | MetabaseAuthConfigWithJwt | MetabaseAuthConfigWithSaml | MetabaseIsGuestAuthConfig;四种模式的判别方式与适用场景对比如下模式判别字段适用场景API KeyapiKey: string仅限本地开发与评估生产环境不支持JWT SSOfetchRequestToken?/preferredAuthMethod?: jwt生产环境的 SSO 认证每个终端用户有自己的账号SAML SSOpreferredAuthMethod?: saml生产环境的 SAML 单点登录GuestisGuest: true无需为访客建号通过 JWT 签名令牌加载嵌入内容在源码 auth-config.ts 中可以看到每种模式的互斥约束是如何编排的MetabaseAuthConfigWithJwtpreferredAuthMethod?: jwt、fetchRequestToken?同时apiKey?: never、isGuest?: falseMetabaseAuthConfigWithSamlpreferredAuthMethod?: samlapiKey?: never、fetchRequestToken?: never、isGuest?: falseMetabaseAuthConfigWithApiKeyapiKey: stringpreferredAuthMethod?: never、fetchRequestToken?: never、isGuest?: false。这样的设计保证了开发者一旦填入 Guest 专属字段TypeScript 编译器就会自动排除其他模式的冲突配置从类型层面杜绝误用。在 MetabaseProvider 中配置 Guest 模式Guest 认证配置通过defineMetabaseAuthConfig函数见 defineMetabaseAuthConfig.md传入 SDK 的MetabaseProviderfunction defineMetabaseAuthConfig( config: MetabaseAuthConfig, ): MetabaseAuthConfig;最小可用的 Guest 配置如果嵌入端已经在 HTML 中预渲染了 JWT 令牌token属性且无需令牌刷新只需配置两个字段import { defineMetabaseAuthConfig, MetabaseProvider } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://metabase.example.com, isGuest: true, }); function App() { return ( MetabaseProvider authConfig{authConfig} {/* 你的嵌入组件 */} /MetabaseProvider ); }启用 JWT 刷新/初始获取的配置如需让嵌入组件在令牌过期时自动向你的后端换取新令牌或首次加载时直接由端点提供首个令牌增加guestEmbedProviderUriconst authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://metabase.example.com, isGuest: true, guestEmbedProviderUri: /api/metabase-guest-token, });注意guestEmbedProviderUri在类型注释与官方文档中均明确标注为iframe only不适用于 SDK 的 Guest 模式。它的两个职责是令牌过期刷新当嵌入当前 JWT 即将过期时组件向端点发起请求换取新 JWT 并替换首次令牌获取当未提供静态token时组件在加载时从端点获取首个 JWT。两种流程都作用于访客嵌入组件metabase-dashboard与metabase-question端点返回格式统一为{ jwt: string }。后端端点示例Node.js / Express参照 guest-embedding.md 中Refreshing or initializing the JWT from your server一节的示例端点应校验请求方身份与权限后签发新令牌const jwt require(jsonwebtoken); const METABASE_SECRET_KEY YOUR_METABASE_SECRET_KEY; app.post(/api/metabase-guest-token, (req, res) { const user req.session?.user; if (!user) { return res.status(403).json({ error: Not signed in }); } const { entityType, entityId, customContext } req.body; if (!userCanView(user, entityType, entityId)) { return res.status(403).json({ error: Not allowed }); } const payload { resource: { [entityType]: entityId }, params: paramsFor(user, customContext), exp: Math.round(Date.now() / 1000) 10 * 60, // 10 分钟过期 }; res.json({ jwt: jwt.sign(payload, METABASE_SECRET_KEY) }); });由于请求携带应用自身的会话 Cookie端点可以对未登录用户返回403拒绝签发对无权查看的仪表盘/问题拒绝签发entityType、entityId来自浏览器必须自行校验否则任何已登录访客都能拿到任意已发布条目的令牌按访客身份计算不同的params即锁定参数值实现按用户过滤数据。Guest 模式的前提先在 Metabase 中发布嵌入内容使用 SDK 的 Guest 模式前需要先在 Metabase 中完成发布动作详见 guest-embedding.md 的 Using guest embeds with the SDK 一节在Admin EmbeddingOSS或Admin Embedding Guest embedsStarter/Pro/Enterprise中开启Enable guest embeds打开要嵌入的仪表盘或问题点击Share图标选择Embed在Authentication下选择Guest可选地设置参数可见性Disabled / Editable / Locked与外观点击Publish。SDK 模式下可以忽略向导生成的代码但必须完成发布Metabase 才会允许向 SDK 提供该条目。此外还有一条重要限制同一页面只能使用一种认证方式例如同一页面上不能同时存在一个 Guest 认证的问题和一个 SSO 认证的问题。源码级原理SDK 如何获取与刷新 Guest 令牌SDK 中 Guest 令牌的获取与刷新逻辑集中在 frontend/src/embedding-sdk-bundle/store/guest-embed/auth.ts包含三个关键动作setInitialGuestToken组件首次加载时写入初始 Guest 令牌以稳定的mountId为键保证同一MetabaseProvider下并发的多个 Guest 嵌入不会互相覆盖令牌clearGuestToken组件卸载时清除对应mountId的令牌避免重新挂载后残留陈旧条目refreshGuestSession/getOrRefreshGuestSession令牌过期时的刷新流程。refreshGuestSession的校验逻辑清晰地印证了guestEmbedProviderUri的必要性与 iframe 限定性export const refreshGuestSession createAsyncThunk( sdk/guest-embed/REFRESH_SESSION, async ({ authConfig, expiredToken }: { authConfig: MetabaseAuthConfig; expiredToken: string; mountId: string }): Promisestring { if (authConfig.isGuest !authConfig.guestEmbedProviderUri) { throw new Error(guestEmbedProviderUri is required to refresh the guest embed token); } if (isEmbeddingEajs()) { return await requestSessionTokenFromEmbedJs({ expiredToken }); } throw new Error(Guest embed token refresh is only supported in iframe embeds); }, );从源码可以归纳出以下实现事实isGuest为真且未配置guestEmbedProviderUri时刷新直接抛错——因此在纯 SDK 场景下若没有静态令牌且不配置该端点令牌过期后将无法续期令牌刷新仅支持 iframe 嵌入即metabase-dashboard/metabase-question这类通过 iframe 渲染的组件或 EAJS 嵌入SDK 原生组件场景下isEmbeddingEajs()为假时会抛出 Guest embed token refresh is only supported in iframe embeds刷新触发条件见getOrRefreshGuestSession当前 Redux 中无令牌、JWT 解码失败或session.exp * 1000 Date.now()令牌已过期时触发刷新未过期则直接复用当前令牌且已发出的刷新请求会被去重复用refreshGuestSessionPromise单例模式。Guest 模式下的数据安全与功能边界安全性基础Guest 嵌入并非不设防Metabase 只会在请求携带用共享密钥签名的 JWT时才加载嵌入内容签名过程见 guest-embedding.md 的 How guest embedding works 一节。JWT 中还包含要加载的资源引用如仪表盘 ID以及参数值。嵌入密钥可在Admin Embedding的Regenerate secret key处重新生成该密钥对所有 Guest 嵌入共享泄露者即可访问全部已嵌入条目务必妥善保管。通过锁定参数Locked Parameters实现按访客过滤Guest 嵌入下 Metabase 不知道访客身份因此无法直接应用行级权限。推荐的隔离手段是锁定参数将参数在嵌入向导中设为Locked然后在服务端把参数值写入 JWT 的params字段如params: { category: [Gadget] }。锁定后终端用户看不到该过滤器但数据已被过滤——例如每个客户只能看到自己的数据。发布含锁定参数的内容后JWT 中必须包含全部锁定参数的名称否则 Metabase 会拒绝请求并记录You must specify a value for :parameter-name in the JWT如需临时跳过某个锁定过滤器可传入空数组[]。功能边界Guest 嵌入不可用能力由于没有为访客建立账号Guest 嵌入无法使用以下能力详见 guest-embedding.md 的 Guest embed limitations 一节行级与列级安全row-and-column-security.md数据库路由database-routing.md下钻分析drill-through见 drill-through.md使用分析usage-analytics.md查询构建器editor.mdAI 对话ai-chat.md自定义可视化custom-visualizations.md如需这些能力应改用 modular-embedding.md 的 SSO 嵌入方案JWT/SAML配置方式见 authentication.md。常见配置陷阱与最佳实践不要把固定 JWT 硬编码进 HTML令牌会过期。要么在服务端每次页面加载时签发新令牌并渲染进token属性要么配置guestEmbedProviderUri让嵌入自行获取/刷新令牌。fetchRequestToken与 Guest 模式互斥该函数属于 JWT SSO 场景类型为() Promise{ jwt: string }见 MetabaseFetchRequestTokenFn.md在MetabaseIsGuestAuthConfig中必须为never。guestEmbedProviderUri端点必须校验entityType/entityId这两个字段来自浏览器请求体若不加校验直接签名任何已登录访客都能获取任意已发布条目的令牌。同一页面单一认证方式Guest 与 SSO 组件不能混用在同一个页面。页面内复用同一仪表盘可通过custom-context属性向端点传递上下文字符串或 JSON 字符串对象端点据此为不同副本签发不同的锁定参数见 guest-embedding.md 的 Sending custom context 一节。小结MetabaseIsGuestAuthConfig是 Embedding SDK 接入 Guest 嵌入的入口类型通过isGuest: true声明访客模式metabaseInstanceUrl指定实例地址guestEmbedProviderUri可选地启用服务端令牌获取与刷新同时用三个never字段与 API Key、JWT、SAML 三种认证方式在类型层面严格互斥。结合锁定参数实现按访客的数据隔离再配合服务端签发的短期 JWT即可在无需 SSO 的前提下安全、轻量地把 Metabase 的仪表盘与问题嵌入到你的应用中。想深入更多细节可继续阅读 guest-embedding.mdGuest 嵌入完整指南、authentication.mdSSO 认证配置以及 SDK 源码 auth-config.ts 与 auth.ts。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考