企业官网建设流程全解析

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

【免费下载链接】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（modular embedding）JWT 单点登录流程中的核心数据契约UserBackendJwtResponse展开，讲解该类型的确切定义、它在前端 SDK 与后端认证服务之间的桥梁作用，以及如何在真实项目中正确实现与之匹配的后端接口与前端fetchRequestToken。读完本文，你将掌握 Metabase 模块化嵌入的 JWT 认证闭环，并能对照仓库源码验证每一步的实现细节。

一、什么是 UserBackendJwtResponse

UserBackendJwtResponse是 Metabase Embedding SDK 定义的一个极其简洁的 TypeScript 响应类型：当你的后端认证服务完成用户身份校验并签发 JSON Web Token 之后，需要向 SDK 返回一个包含jwt字段的 JSON 对象，这个对象的类型就是UserBackendJwtResponse。

在仓库中，该类型的完整定义位于 frontend/src/metabase/embedding-sdk/types/refresh-token.ts：

export type UserBackendJwtResponse = { jwt: string; };

在 SDK 的类型文档（docs/embedding/sdk/api/snippets/UserBackendJwtResponse.md）中，它被描述为：

type UserBackendJwtResponse = { jwt: string; };

该类型只有一个属性：

二、该类型在 SDK 中的位置：fetchRequestToken 的返回值

UserBackendJwtResponse不是孤立存在的类型，它是整个 SDK JWT 认证链路的出口契约。在同一个源码文件中，SDK 定义了请求 Token 的函数类型：

export type MetabaseFetchRequestTokenFn = () => Promise<UserBackendJwtResponse>;

也就是说，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 也给出了一致的表格说明：

由此可以得出整条契约链：

MetabaseAuthConfigWithJwt.fetchRequestToken │ 类型为 ▼ MetabaseFetchRequestTokenFn = () => Promise<UserBackendJwtResponse> │ resolve 为 ▼ { jwt: string } ← 即后端认证接口必须返回的 JSON 形状

三、为什么后端必须返回 { jwt: string }

SDK 拿到{ jwt: string }之后，会拿其中的 JWT 去 Metabase 换取会话：modular embedding 场景下，Metabase 通过POST /auth/sso并携带 JSON 请求体（而非全应用嵌入常用的 GET 重定向）来交换 JWT。完整流程见 docs/embedding/authentication.md：

1. 在 MetabaseAdmin>Settings>Authentication中启用 JWT，并填写JWT Identity Provider URI，例如http://localhost:9090/sso/metabase（这是你在后端新增的认证端点）。
2. 在你的后端新增一个认证端点，使用 Metabase 的 JWT 共享密钥为当前已登录用户签发 JWT。
3. 该端点必须返回一个带jwt属性的 JSON 对象，例如{ "jwt": "your-signed-jwt" }——这正是UserBackendJwtResponse的定义。
4. 前端把metabaseInstanceUrl与可选的fetchRequestToken交给MetabaseProvider，SDK 通过fetchRequestToken向后端取令牌。

后端端点的示例实现

官方文档给出了一个同时兼容 SDK 请求与全应用嵌入请求的 Express 端点写法（对应 docs/embedding/authentication.md 中的升级指引）：

app.get("/sso/metabase", async (req, res) => { // SDK 请求会附带 'response=json' 查询参数，用于与全应用嵌入请求区分 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?token=true&jwt=${token}`; res.redirect(ssoUrl); } });

注意这里两个分支的核心差异：SDK 请求返回 JSON（与UserBackendJwtResponse形状一致），全应用嵌入请求返回重定向。如果你的后端同时服务两类嵌入，必须用response=json参数区分。

四、前端如何消费该契约：fetchRequestToken 实战

UserBackendJwtResponse的消费端是fetchRequestToken。仓库中的完整示例位于 docs/embedding/sdk/snippets/authentication/auth-config-jwt.tsx：

import { 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

除了fetchRequestToken，MetabaseAuthConfigWithJwt还提供可选的jwtProviderUri属性：如果提供，SDK 会直接使用 JWT 认证，并跳过首次的/auth/sso发现请求（即 SDK 不再去探测 Metabase 支持哪种 SSO 方式）。对于明确只使用 JWT 的场景，这可以省去一次网络往返。

五、版本升级注意事项（SDK 1.54 及以下）

官方文档 docs/embedding/authentication.md 专门列出了从 SDK 1.54.x 及以下版本升级到 JWT SSO 新流程时需要调整的三处，全部与UserBackendJwtResponse契约相关：

1. 前端移除authProviderUri：defineMetabaseAuthConfig不再接受authProviderUri参数，JWT Identity Provider URI 改由 Metabase 管理后台（Admin > Settings > Authentication > JWT）配置。

2. 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", });

3. 后端端点升级：端点必须同时处理 SDK 请求与全应用嵌入请求，SDK 请求以response=json查询参数标识，需要返回{ jwt: string }JSON（即UserBackendJwtResponse），全应用嵌入请求继续重定向。前文第三节的 Express 示例即为此实现。

六、与认证方式选择的关联

UserBackendJwtResponse只在 JWT 认证路径下生效。MetabaseAuthConfig是一个联合类型（见 docs/embedding/sdk/api/snippets/MetabaseAuthConfig.md）：

type MetabaseAuthConfig = | MetabaseAuthConfigWithApiKey | MetabaseAuthConfigWithJwt | MetabaseAuthConfigWithSaml | MetabaseIsGuestAuthConfig;

• JWT：通过fetchRequestToken返回{ jwt: string }，即本文主题；
• SAML：fetchRequestToken被类型层面禁止（fetchRequestToken?: never），认证走弹出窗口重定向，无法实现自定义的fetchRequestToken；
• API Key：仅用于本地开发与评估，fetchRequestToken同样为never；
• Guest：无登录用户，直接使用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以它为返回值把令牌交给 SDK，SDK 再通过/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