Metabase Embedding SDK 的 UserBackendJwtResponse：JWT 认证响应契约深度解析

Metabase Embedding SDK 的 UserBackendJwtResponseJWT 认证响应契约深度解析【免费下载链接】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 SDKmodular embeddingJWT 单点登录流程中的核心数据契约UserBackendJwtResponse展开讲解该类型的确切定义、它在前端 SDK 与后端认证服务之间的桥梁作用以及如何在真实项目中正确实现与之匹配的后端接口与前端fetchRequestToken。读完本文你将掌握 Metabase 模块化嵌入的 JWT 认证闭环并能对照仓库源码验证每一步的实现细节。一、什么是 UserBackendJwtResponseUserBackendJwtResponse是 Metabase Embedding SDK 定义的一个极其简洁的 TypeScript 响应类型当你的后端认证服务完成用户身份校验并签发 JSON Web Token 之后需要向 SDK 返回一个包含jwt字段的 JSON 对象这个对象的类型就是UserBackendJwtResponse。在仓库中该类型的完整定义位于 frontend/src/metabase/embedding-sdk/types/refresh-token.tsexport type UserBackendJwtResponse { jwt: string; };在 SDK 的类型文档docs/embedding/sdk/api/snippets/UserBackendJwtResponse.md中它被描述为type UserBackendJwtResponse { jwt: string; };该类型只有一个属性PropertyType说明jwtstring后端为当前登录用户签发的 JWT 字符串二、该类型在 SDK 中的位置fetchRequestToken 的返回值UserBackendJwtResponse不是孤立存在的类型它是整个 SDK JWT 认证链路的出口契约。在同一个源码文件中SDK 定义了请求 Token 的函数类型export type MetabaseFetchRequestTokenFn () PromiseUserBackendJwtResponse;也就是说MetabaseFetchRequestTokenFn是一个「无参异步函数」其返回值必须是一个Promise最终 resolve 为一个UserBackendJwtResponse即{ jwt: string }。类型文档 docs/embedding/sdk/api/snippets/MetabaseFetchRequestTokenFn.md 中对返回值的描述与此完全一致type MetabaseFetchRequestTokenFn () Promise{ jwt: string; };再往上追溯fetchRequestToken是 JWT 认证配置MetabaseAuthConfigWithJwt的一个可选属性。在 frontend/src/embedding-sdk-shared/types/auth-config.ts 中可以看到它的类型声明与注释export type MetabaseAuthConfigWithJwt BaseMetabaseAuthConfig { preferredAuthMethod?: jwt; jwtProviderUri?: string; /** * Specifies a function to fetch the refresh token. * The refresh token should be in the format of {link UserBackendJwtResponse} */ fetchRequestToken?: MetabaseFetchRequestTokenFn; isGuest?: false; apiKey?: never; };这段源码注释明确写道The refresh token should be in the format of UserBackendJwtResponse——即fetchRequestToken取到的「刷新令牌」必须符合UserBackendJwtResponse的格式。类型文档 docs/embedding/sdk/api/snippets/MetabaseAuthConfigWithJwt.md 也给出了一致的表格说明NameTypeDescriptionapiKey?never-fetchRequestToken?MetabaseFetchRequestTokenFnSpecifies a function to fetch the refresh token. The refresh token should be in the format of UserBackendJwtResponseisGuest?false-jwtProviderUri?stringUri of the jwt provider. If provided the sdk will use jwt and will skip the first/auth/ssodiscovery request.preferredAuthMethod?jwtWhich authentication method to use. If both SAML and JWT are enabled at the same time, it defaults to SAML unless the preferredAuthMethod is specified.由此可以得出整条契约链MetabaseAuthConfigWithJwt.fetchRequestToken │ 类型为 ▼ MetabaseFetchRequestTokenFn () PromiseUserBackendJwtResponse │ resolve 为 ▼ { jwt: string } ← 即后端认证接口必须返回的 JSON 形状三、为什么后端必须返回 { jwt: string }SDK 拿到{ jwt: string }之后会拿其中的 JWT 去 Metabase 换取会话modular embedding 场景下Metabase 通过POST /auth/sso并携带 JSON 请求体而非全应用嵌入常用的 GET 重定向来交换 JWT。完整流程见 docs/embedding/authentication.md在 MetabaseAdminSettingsAuthentication中启用 JWT并填写JWT Identity Provider URI例如http://localhost:9090/sso/metabase这是你在后端新增的认证端点。在你的后端新增一个认证端点使用 Metabase 的 JWT 共享密钥为当前已登录用户签发 JWT。该端点必须返回一个带jwt属性的 JSON 对象例如{ jwt: your-signed-jwt }——这正是UserBackendJwtResponse的定义。前端把metabaseInstanceUrl与可选的fetchRequestToken交给MetabaseProviderSDK 通过fetchRequestToken向后端取令牌。后端端点的示例实现官方文档给出了一个同时兼容 SDK 请求与全应用嵌入请求的 Express 端点写法对应 docs/embedding/authentication.md 中的升级指引app.get(/sso/metabase, async (req, res) { // SDK 请求会附带 responsejson 查询参数用于与全应用嵌入请求区分 const isSdkRequest req.query.response json; const user getCurrentUser(req); const token jwt.sign( { email: user.email, first_name: user.firstName, last_name: user.lastName, groups: [user.group], exp: Math.round(Date.now() / 1000) 60 * 10, }, METABASE_JWT_SHARED_SECRET, ); if (isSdkRequest) { // 对 SDK 请求返回 { jwt: string }即 UserBackendJwtResponse res.status(200).json({ jwt: token }); } else { // 对全应用嵌入请求继续走原来的重定向逻辑 const ssoUrl ${METABASE_INSTANCE_URL}/auth/sso?tokentruejwt${token}; res.redirect(ssoUrl); } });注意这里两个分支的核心差异SDK 请求返回 JSON与UserBackendJwtResponse形状一致全应用嵌入请求返回重定向。如果你的后端同时服务两类嵌入必须用responsejson参数区分。四、前端如何消费该契约fetchRequestToken 实战UserBackendJwtResponse的消费端是fetchRequestToken。仓库中的完整示例位于 docs/embedding/sdk/snippets/authentication/auth-config-jwt.tsximport { defineMetabaseAuthConfig } from metabase/embedding-sdk-react; const yourToken token; // 将配置传给 MetabaseProvider。 // 如果 fetchRequestToken 有依赖建议用 useCallback 包裹以防止多余的重渲染。 const authConfig defineMetabaseAuthConfig({ fetchRequestToken: async () { const response await fetch( https://{{ YOUR_CLIENT_HOST }}/api/metabase/auth, { method: GET, headers: { Authorization: Bearer ${yourToken} }, }, ); // 后端应返回形状为 { jwt: string } 的 JSON 对象 return await response.json(); }, metabaseInstanceUrl: http://localhost:3000, });要点总结fetchRequestToken不接受任何参数你需要在函数内部硬编码你的认证端点 URL这一行为自 SDK 1.54 版本调整后成为规范详见下文。函数体负责向后端发起请求并把响应直接await response.json()返回只要后端返回的是{ jwt: string }就天然满足UserBackendJwtResponse。如果fetchRequestToken依赖组件内的 state 或 props应当用useCallback包裹避免因函数引用变化触发 SDK 重复拉取 Token。若想进一步定制请求头例如用 header 而不是 cookie 传递你的应用侧凭证同样在这个函数中实现官方文档称之为「Customizing JWT authentication」。非必须的 jwtProviderUri除了fetchRequestTokenMetabaseAuthConfigWithJwt还提供可选的jwtProviderUri属性如果提供SDK 会直接使用 JWT 认证并跳过首次的/auth/sso发现请求即 SDK 不再去探测 Metabase 支持哪种 SSO 方式。对于明确只使用 JWT 的场景这可以省去一次网络往返。五、版本升级注意事项SDK 1.54 及以下官方文档 docs/embedding/authentication.md 专门列出了从 SDK 1.54.x 及以下版本升级到 JWT SSO 新流程时需要调整的三处全部与UserBackendJwtResponse契约相关前端移除authProviderUridefineMetabaseAuthConfig不再接受authProviderUri参数JWT Identity Provider URI 改由 Metabase 管理后台Admin Settings Authentication JWT配置。fetchRequestToken签名变更旧版函数接收一个url参数新版无参端点 URL 必须在函数内部写死// Before旧版需移除 url 参数与 authProviderUri const authConfig defineMetabaseAuthConfig({ fetchRequestToken: async (url) { const response await fetch(url, { method: GET, headers: { Authorization: Bearer ${yourToken} }, }); return await response.json(); }, metabaseInstanceUrl: http://localhost:3000, authProviderUri: http://localhost:9090/sso/metabase, }); // After新版 const authConfig defineMetabaseAuthConfig({ fetchRequestToken: async () { const response await fetch(http://localhost:9090/sso/metabase, { method: GET, headers: { Authorization: Bearer ${yourToken} }, }); return await response.json(); }, metabaseInstanceUrl: http://localhost:3000, });后端端点升级端点必须同时处理 SDK 请求与全应用嵌入请求SDK 请求以responsejson查询参数标识需要返回{ jwt: string }JSON即UserBackendJwtResponse全应用嵌入请求继续重定向。前文第三节的 Express 示例即为此实现。六、与认证方式选择的关联UserBackendJwtResponse只在 JWT 认证路径下生效。MetabaseAuthConfig是一个联合类型见 docs/embedding/sdk/api/snippets/MetabaseAuthConfig.mdtype MetabaseAuthConfig | MetabaseAuthConfigWithApiKey | MetabaseAuthConfigWithJwt | MetabaseAuthConfigWithSaml | MetabaseIsGuestAuthConfig;JWT通过fetchRequestToken返回{ jwt: string }即本文主题SAMLfetchRequestToken被类型层面禁止fetchRequestToken?: never认证走弹出窗口重定向无法实现自定义的fetchRequestTokenAPI Key仅用于本地开发与评估fetchRequestToken同样为neverGuest无登录用户直接使用isGuest: true。此外当 Metabase 同时启用了 SAML 与 JWT 时SDK 默认优先使用 SAML如需强制走 JWT应在配置中显式设置preferredAuthMethod: jwt。七、安全提醒每个终端用户必须有独立 Metabase 账户使用 JWT 认证嵌入时后端签发的 JWT 代表具体用户因此每个终端用户都必须拥有自己的 Metabase 账户。如果让终端用户共享一个账户即便前端做了数据过滤所有用户仍能拿到会话令牌并可能通过 Metabase API 直接访问本不该看到的数据而为每个用户分配独立账户后Metabase 的权限体系才能真正生效。这一点在 docs/embedding/authentication.md 中被列为安全警告也是设计{ jwt: string }契约的出发点——JWT 内容如email、groups由后端按当前登录用户动态生成。小结UserBackendJwtResponse虽然只有一个jwt字段却是 Metabase Embedding SDK JWT 认证闭环的关键枢纽后端以它为返回契约签发令牌fetchRequestToken以它为返回值把令牌交给 SDKSDK 再通过/auth/sso换取 Metabase 会话。理解这条契约链你就能在任意后端框架Express、Next.js App Router、Pages Router 等上正确实现与 SDK 配套的认证端点并在升级 SDK 时快速定位需要同步修改的签名与响应格式。想深入了解完整接入流程可继续阅读 docs/embedding/authentication.md 与 docs/embedding/sdk/api/index.md。【免费下载链接】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），仅供参考