尧图网站建设 
Metabase Embedding SDKMetabaseAuthConfigWithJwt 类型详解——用 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/metabaseMetabaseAuthConfigWithJwt是 Metabase React Embedding SDK 中MetabaseAuthConfig联合类型里代表JWT 认证模式的分支。读懂这个类型就能掌握在宿主应用中通过身份提供者签发的 JWT 换取 Metabase 会话令牌session token的完整认证链路包括jwtProviderUri如何跳过 SSO discovery、fetchRequestToken如何接管令牌刷新、以及preferredAuthMethod在多 SSO 共存时的取舍规则。读完本文你可以直接在自己的宿主应用中写出可编译、可运行的 JWT 嵌入认证配置并理解其底层的 HTTP 调用流程。类型定义与字段全览该类型定义位于 auth-config.ts它是基础字段与 JWT 专属字段的交集type MetabaseAuthConfigWithJwt { metabaseInstanceUrl: string; } { apiKey?: never; fetchRequestToken?: MetabaseFetchRequestTokenFn; isGuest?: false; jwtProviderUri?: string; preferredAuthMethod?: jwt; };其中BaseMetabaseAuthConfig只有一个必填字段JWT 专属字段则约束了认证方式互斥的语义。各字段说明如下继承自 MetabaseAuthConfigWithJwt 类型文档字段类型说明metabaseInstanceUrlstring必填。Metabase 实例的 URLSDK 所有的认证请求都以此为基址apiKey?never禁止提供。apiKey 属于另一分支MetabaseAuthConfigWithApiKey出现即类型报错fetchRequestToken?MetabaseFetchRequestTokenFn指定获取刷新token 的函数返回值格式须为UserBackendJwtResponse即{ jwt: string }isGuest?false该分支仅服务已认证用户场景访客模式走MetabaseIsGuestAuthConfigisGuest: truejwtProviderUri?stringJWT 提供者的 URI。提供后 SDK 直接使用 JWT并跳过对/auth/sso的首次 discovery 请求preferredAuthMethod?jwt指定认证方法。当 SAML 与 JWT 同时启用时默认使用 SAML除非显式指定preferredAuthMethod这个类型并非孤立存在。在 auth-config.ts 中MetabaseAuthConfig是四个分支的联合类型MetabaseAuthConfigWithApiKey、MetabaseAuthConfigWithJwt、MetabaseAuthConfigWithSaml和MetabaseIsGuestAuthConfig。各分支通过apiKey?: never、fetchRequestToken?: never、preferredAuthMethod?: never这类never 字段实现 TypeScript 层面的互斥约束——如果你给 JWT 配置对象加上apiKey编译器会立刻报错。这正是原文档中apiKey?: never一栏的技术含义。fetchRequestToken 的函数签名与返回值fetchRequestToken是 SDK 与你后端之间唯一的令牌注入点。其类型定义在 refresh-token.tsexport type UserBackendJwtResponse { jwt: string; }; export type MetabaseFetchRequestTokenFn () PromiseUserBackendJwtResponse;要点有三异步函数() PromiseUserBackendJwtResponse宿主应用通常在此回调里请求自己的后端可能带用户 cookie由后端签出或换发一个 Metabase 可验证的 JWT。返回值格式强制为{ jwt: string }这不是可选约定。源码中 jwt.ts 的runFetchRequestToken会显式校验响应对象若不满足typeof res object jwt in res会抛出CUSTOM_FETCH_REQUEST_TOKEN_ERROR期望值{ jwt: string }实际值一并给出方便排查。一个没有参数、没有 token 的函数签名不接收过期 token每次调用都是拉取当前用户的新 token刷新语义由函数内部实现。fetchRequestToken也出现在 iframe SDK 一侧的设置类型中见 embed.ts 的SdkIframeEmbedBaseSettings与 auth-manager.ts 的EmbedAuthManagerContext说明组件式React SDK与metabase-embed标签式两种嵌入形态共享同一套 JWT 认证参数语义。jwtProviderUri跳过 discovery 的直连通道jwtProviderUri是控制 SDK 走哪条认证路径的关键字段其运行时行为可以从 bootstrap-auth.ts 的performFullAuthFlow中完整还原// Step 1: SSO discovery (skip if jwtProviderUri provided) const ssoResult config.jwtProviderUri ? { method: jwt as const, url: config.jwtProviderUri } : await connectToInstanceAuthSso(config.metabaseInstanceUrl, { headers, preferredAuthMethod: config.preferredAuthMethod, });不传jwtProviderUriSDK 先调用 Metabase 的 SSO discoveryconnectToInstanceAuthSso由 Metabase 侧告知当前启用了哪些认证方式及其端点preferredAuthMethod在此阶段作为偏好参数传入。传了jwtProviderUriSDK 直接把该 URI 当作获取 JWT 的端点使用省掉一次 discovery 往返。这正是类型文档中skip the first /auth/sso discovery request描述的源码依据。若 discovery 结果不是jwt例如只启用了 SAMLperformFullAuthFlow返回null并回落到需要用户交互的常规认证流程SAML 需要弹出登录窗口无法预取。jwtProviderUri指向的端点需要满足什么在 jwt.ts 的refreshUserJwt中可以看到SDK 以 GET 方式请求该 URI附加?responsejson查询参数、credentials: include响应体需为 JSON 且形如{ jwt: signed-token }。URI 支持相对路径——源码用new URL(url, window.location.origin)解析因此可以写/api/sso这类相对宿主域的路径。网络失败、HTTP 非 2xx、JSON 解析失败分别会抛出CANNOT_FETCH_JWT_TOKEN或DEFAULT_ENDPOINT_ERROR。JWT 换取会话令牌的完整流程无论 JWT 来自 discovery 还是jwtProviderUri直连后续流程统一由 jwt.ts 的jwtDefaultRefreshTokenFunction完成调用runFetchRequestToken若宿主传了fetchRequestToken则调用自定义函数否则用jwtProviderUri做默认 GET 请求见上文。将拿到的 JWT 通过POST提交到${metabaseInstanceUrl}/auth/sso请求体为JSON.stringify({ jwt })——使用 POST JSON body 而非把 token 放进 URL避免 JWT 出现在访问日志和 URL 缓存中与 JWT 认证官方文档 对模块化嵌入用 POST 请求并带 JSON body的建议一致。成功时返回 Metabase 会话响应解析失败抛DEFAULT_ENDPOINT_ERROR网络/状态错误抛CANNOT_FETCH_JWT_TOKEN。会话有效后bootstrap-auth.ts 会并行拉取/api/user/current与/api/session/properties请求头携带X-Metabase-Session与X-Metabase-Client: embedding-sdk-react完成用户与站点设置的预热。值得强调的是这段提前认证发生在 bootstrap 阶段见 bootstrap-auth.ts 的注释认证在主 bundle 加载完成前并行启动且明确排除两种情况——配置了apiKey或preferredAuthMethod saml时会直接skipped只有 JWT 路径适合无感预取。会话过期后SDK 通过 auth.ts 的refreshTokenAsyncthunk 触发刷新其参数{ metabaseInstanceUrl, preferredAuthMethod, jwtProviderUri }与类型定义逐一对应OSS 侧是空实现的插件点真正的刷新逻辑由 EE 的认证插件注入从该文件注释we co-locate it with its OSS usage... for better tree-shaking可以推断这种插件化拆分方式。preferredAuthMethod 与互斥约束preferredAuthMethod取jwt本分支或samlMetabaseAuthConfigWithSaml分支。它的存在针对一个具体场景Metabase 实例同时启用了 SAML 与 JWT 两种 SSO 时discovery 的默认选择是 SAML只有显式设置preferredAuthMethod: jwt才能让 SDK 走 JWT 分支——类型文档中的描述与 auth-config.ts 上的 JSDoc 注释完全一致。类型层面还有一组负向约束值得注意它们把四种认证模式的边界固化在了编译期export type MetabaseAuthConfigWithApiKey BaseMetabaseAuthConfig { apiKey: string; isGuest?: false; preferredAuthMethod?: never; // apiKey 模式不接受 preferredAuthMethod fetchRequestToken?: never; // 也不接受 fetchRequestToken };即preferredAuthMethod只在 SAML/JWT 两种 SSO 方式需要二选一时有意义apiKey 与 guest 模式下它被标为never。同时文件末尾导出的MetabaseAuthMethod ExcludeMetabaseAuthConfig[preferredAuthMethod], undefined见 auth-config.ts就是运行时代码里jwt | saml联合类型的来源。一个可运行的配置示例综合以上约束一个典型的 JWT 认证配置如下以jwtProviderUri直连、不使用自定义fetchRequestToken为例import { MetabaseProvider } from metabase/embedding-sdk-react; MetabaseProvider authConfig{{ metabaseInstanceUrl: https://metabase.example.com, jwtProviderUri: /api/sso/token, // 你的后端端点GET 后返回 { jwt: ... } }} MetabaseDashboardEmbed dashboardId{1} / /MetabaseProvider;若希望保留 discovery让 Metabase 决定端点并在 SAML/JWT 共存时强制 JWT则换成authConfig{{ metabaseInstanceUrl: https://metabase.example.com, preferredAuthMethod: jwt, }}若令牌的获取需要带宿主应用的认证上下文如读取 cookie 后再调后端则提供fetchRequestToken并省略jwtProviderUri此时 discovery 仍会执行但取 token 的动作完全交给你的函数authConfig{{ metabaseInstanceUrl: https://metabase.example.com, preferredAuthMethod: jwt, fetchRequestToken: async () { const res await fetch(/api/my-backend/jwt, { credentials: include }); return res.json(); // 必须解析为 { jwt: string } }, }}注意三条容易踩坑的边界fetchRequestToken的返回值若缺少jwt键会抛CUSTOM_FETCH_REQUEST_TOKEN_ERRORjwtProviderUri端点的响应不是{ jwt: string }的 JSON 会抛DEFAULT_ENDPOINT_ERROR与 Metabase 的/auth/sso交换失败会抛CANNOT_FETCH_JWT_TOKEN携带 URL 与 status/message见 jwt.ts。适用前提与限制JWT 认证是 Metabase 企业版特性JWT-based authentication 文档 顶部带有付费功能标注需要在 Metabase 管理后台Authentication JWT中配置 JWT Identity Provider URI 与签名密钥本类型仅描述 SDK 侧的客户端配置服务端配置不在其覆盖范围内。MetabaseAuthConfigWithJwt描述的是 React SDK 的authConfig分支metabase-embediframe 标签形态在 embed.ts 中以扁平字段instanceUrl、jwtProviderUri、fetchRequestToken、preferredAuthMethod表达同样的语义注意字段名差异metabaseInstanceUrlvsinstanceUrl。访客嵌入isGuest: true不走本类型它属于MetabaseIsGuestAuthConfig分支使用guestEmbedProviderUri而非jwtProviderUri。小结MetabaseAuthConfigWithJwt用一个 TypeScript 交叉类型把 JWT 嵌入认证的三种可选能力——jwtProviderUri直连取 token、跳过 discovery、fetchRequestToken自定义取 token、preferredAuthMethodSAML/JWT 共存时的显式选择——与必填的metabaseInstanceUrl组合在一起并用never字段与其他认证分支划清边界。源码层面的证据链清晰类型定义在 auth-config.ts取 token 与交换会话的 HTTP 流程在 jwt.ts提前认证与会话刷新入口分别在 bootstrap-auth.ts 和 auth.ts。沿着这几处文件可以完整复现从宿主应用 JWT 到 Metabase 会话令牌的全链路。【免费下载链接】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），仅供参考 Metabase Embedding SDK：MetabaseAuthConfigWithJwt 类型详解——用 JWT 完成模块化嵌入认证
Metabase Embedding SDKMetabaseAuthConfigWithJwt 类型详解——用 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/metabaseMetabaseAuthConfigWithJwt是 Metabase React Embedding SDK 中MetabaseAuthConfig联合类型里代表JWT 认证模式的分支。读懂这个类型就能掌握在宿主应用中通过身份提供者签发的 JWT 换取 Metabase 会话令牌session token的完整认证链路包括jwtProviderUri如何跳过 SSO discovery、fetchRequestToken如何接管令牌刷新、以及preferredAuthMethod在多 SSO 共存时的取舍规则。读完本文你可以直接在自己的宿主应用中写出可编译、可运行的 JWT 嵌入认证配置并理解其底层的 HTTP 调用流程。类型定义与字段全览该类型定义位于 auth-config.ts它是基础字段与 JWT 专属字段的交集type MetabaseAuthConfigWithJwt { metabaseInstanceUrl: string; } { apiKey?: never; fetchRequestToken?: MetabaseFetchRequestTokenFn; isGuest?: false; jwtProviderUri?: string; preferredAuthMethod?: jwt; };其中BaseMetabaseAuthConfig只有一个必填字段JWT 专属字段则约束了认证方式互斥的语义。各字段说明如下继承自 MetabaseAuthConfigWithJwt 类型文档字段类型说明metabaseInstanceUrlstring必填。Metabase 实例的 URLSDK 所有的认证请求都以此为基址apiKey?never禁止提供。apiKey 属于另一分支MetabaseAuthConfigWithApiKey出现即类型报错fetchRequestToken?MetabaseFetchRequestTokenFn指定获取刷新token 的函数返回值格式须为UserBackendJwtResponse即{ jwt: string }isGuest?false该分支仅服务已认证用户场景访客模式走MetabaseIsGuestAuthConfigisGuest: truejwtProviderUri?stringJWT 提供者的 URI。提供后 SDK 直接使用 JWT并跳过对/auth/sso的首次 discovery 请求preferredAuthMethod?jwt指定认证方法。当 SAML 与 JWT 同时启用时默认使用 SAML除非显式指定preferredAuthMethod这个类型并非孤立存在。在 auth-config.ts 中MetabaseAuthConfig是四个分支的联合类型MetabaseAuthConfigWithApiKey、MetabaseAuthConfigWithJwt、MetabaseAuthConfigWithSaml和MetabaseIsGuestAuthConfig。各分支通过apiKey?: never、fetchRequestToken?: never、preferredAuthMethod?: never这类never 字段实现 TypeScript 层面的互斥约束——如果你给 JWT 配置对象加上apiKey编译器会立刻报错。这正是原文档中apiKey?: never一栏的技术含义。fetchRequestToken 的函数签名与返回值fetchRequestToken是 SDK 与你后端之间唯一的令牌注入点。其类型定义在 refresh-token.tsexport type UserBackendJwtResponse { jwt: string; }; export type MetabaseFetchRequestTokenFn () PromiseUserBackendJwtResponse;要点有三异步函数() PromiseUserBackendJwtResponse宿主应用通常在此回调里请求自己的后端可能带用户 cookie由后端签出或换发一个 Metabase 可验证的 JWT。返回值格式强制为{ jwt: string }这不是可选约定。源码中 jwt.ts 的runFetchRequestToken会显式校验响应对象若不满足typeof res object jwt in res会抛出CUSTOM_FETCH_REQUEST_TOKEN_ERROR期望值{ jwt: string }实际值一并给出方便排查。一个没有参数、没有 token 的函数签名不接收过期 token每次调用都是拉取当前用户的新 token刷新语义由函数内部实现。fetchRequestToken也出现在 iframe SDK 一侧的设置类型中见 embed.ts 的SdkIframeEmbedBaseSettings与 auth-manager.ts 的EmbedAuthManagerContext说明组件式React SDK与metabase-embed标签式两种嵌入形态共享同一套 JWT 认证参数语义。jwtProviderUri跳过 discovery 的直连通道jwtProviderUri是控制 SDK 走哪条认证路径的关键字段其运行时行为可以从 bootstrap-auth.ts 的performFullAuthFlow中完整还原// Step 1: SSO discovery (skip if jwtProviderUri provided) const ssoResult config.jwtProviderUri ? { method: jwt as const, url: config.jwtProviderUri } : await connectToInstanceAuthSso(config.metabaseInstanceUrl, { headers, preferredAuthMethod: config.preferredAuthMethod, });不传jwtProviderUriSDK 先调用 Metabase 的 SSO discoveryconnectToInstanceAuthSso由 Metabase 侧告知当前启用了哪些认证方式及其端点preferredAuthMethod在此阶段作为偏好参数传入。传了jwtProviderUriSDK 直接把该 URI 当作获取 JWT 的端点使用省掉一次 discovery 往返。这正是类型文档中skip the first /auth/sso discovery request描述的源码依据。若 discovery 结果不是jwt例如只启用了 SAMLperformFullAuthFlow返回null并回落到需要用户交互的常规认证流程SAML 需要弹出登录窗口无法预取。jwtProviderUri指向的端点需要满足什么在 jwt.ts 的refreshUserJwt中可以看到SDK 以 GET 方式请求该 URI附加?responsejson查询参数、credentials: include响应体需为 JSON 且形如{ jwt: signed-token }。URI 支持相对路径——源码用new URL(url, window.location.origin)解析因此可以写/api/sso这类相对宿主域的路径。网络失败、HTTP 非 2xx、JSON 解析失败分别会抛出CANNOT_FETCH_JWT_TOKEN或DEFAULT_ENDPOINT_ERROR。JWT 换取会话令牌的完整流程无论 JWT 来自 discovery 还是jwtProviderUri直连后续流程统一由 jwt.ts 的jwtDefaultRefreshTokenFunction完成调用runFetchRequestToken若宿主传了fetchRequestToken则调用自定义函数否则用jwtProviderUri做默认 GET 请求见上文。将拿到的 JWT 通过POST提交到${metabaseInstanceUrl}/auth/sso请求体为JSON.stringify({ jwt })——使用 POST JSON body 而非把 token 放进 URL避免 JWT 出现在访问日志和 URL 缓存中与 JWT 认证官方文档 对模块化嵌入用 POST 请求并带 JSON body的建议一致。成功时返回 Metabase 会话响应解析失败抛DEFAULT_ENDPOINT_ERROR网络/状态错误抛CANNOT_FETCH_JWT_TOKEN。会话有效后bootstrap-auth.ts 会并行拉取/api/user/current与/api/session/properties请求头携带X-Metabase-Session与X-Metabase-Client: embedding-sdk-react完成用户与站点设置的预热。值得强调的是这段提前认证发生在 bootstrap 阶段见 bootstrap-auth.ts 的注释认证在主 bundle 加载完成前并行启动且明确排除两种情况——配置了apiKey或preferredAuthMethod saml时会直接skipped只有 JWT 路径适合无感预取。会话过期后SDK 通过 auth.ts 的refreshTokenAsyncthunk 触发刷新其参数{ metabaseInstanceUrl, preferredAuthMethod, jwtProviderUri }与类型定义逐一对应OSS 侧是空实现的插件点真正的刷新逻辑由 EE 的认证插件注入从该文件注释we co-locate it with its OSS usage... for better tree-shaking可以推断这种插件化拆分方式。preferredAuthMethod 与互斥约束preferredAuthMethod取jwt本分支或samlMetabaseAuthConfigWithSaml分支。它的存在针对一个具体场景Metabase 实例同时启用了 SAML 与 JWT 两种 SSO 时discovery 的默认选择是 SAML只有显式设置preferredAuthMethod: jwt才能让 SDK 走 JWT 分支——类型文档中的描述与 auth-config.ts 上的 JSDoc 注释完全一致。类型层面还有一组负向约束值得注意它们把四种认证模式的边界固化在了编译期export type MetabaseAuthConfigWithApiKey BaseMetabaseAuthConfig { apiKey: string; isGuest?: false; preferredAuthMethod?: never; // apiKey 模式不接受 preferredAuthMethod fetchRequestToken?: never; // 也不接受 fetchRequestToken };即preferredAuthMethod只在 SAML/JWT 两种 SSO 方式需要二选一时有意义apiKey 与 guest 模式下它被标为never。同时文件末尾导出的MetabaseAuthMethod ExcludeMetabaseAuthConfig[preferredAuthMethod], undefined见 auth-config.ts就是运行时代码里jwt | saml联合类型的来源。一个可运行的配置示例综合以上约束一个典型的 JWT 认证配置如下以jwtProviderUri直连、不使用自定义fetchRequestToken为例import { MetabaseProvider } from metabase/embedding-sdk-react; MetabaseProvider authConfig{{ metabaseInstanceUrl: https://metabase.example.com, jwtProviderUri: /api/sso/token, // 你的后端端点GET 后返回 { jwt: ... } }} MetabaseDashboardEmbed dashboardId{1} / /MetabaseProvider;若希望保留 discovery让 Metabase 决定端点并在 SAML/JWT 共存时强制 JWT则换成authConfig{{ metabaseInstanceUrl: https://metabase.example.com, preferredAuthMethod: jwt, }}若令牌的获取需要带宿主应用的认证上下文如读取 cookie 后再调后端则提供fetchRequestToken并省略jwtProviderUri此时 discovery 仍会执行但取 token 的动作完全交给你的函数authConfig{{ metabaseInstanceUrl: https://metabase.example.com, preferredAuthMethod: jwt, fetchRequestToken: async () { const res await fetch(/api/my-backend/jwt, { credentials: include }); return res.json(); // 必须解析为 { jwt: string } }, }}注意三条容易踩坑的边界fetchRequestToken的返回值若缺少jwt键会抛CUSTOM_FETCH_REQUEST_TOKEN_ERRORjwtProviderUri端点的响应不是{ jwt: string }的 JSON 会抛DEFAULT_ENDPOINT_ERROR与 Metabase 的/auth/sso交换失败会抛CANNOT_FETCH_JWT_TOKEN携带 URL 与 status/message见 jwt.ts。适用前提与限制JWT 认证是 Metabase 企业版特性JWT-based authentication 文档 顶部带有付费功能标注需要在 Metabase 管理后台Authentication JWT中配置 JWT Identity Provider URI 与签名密钥本类型仅描述 SDK 侧的客户端配置服务端配置不在其覆盖范围内。MetabaseAuthConfigWithJwt描述的是 React SDK 的authConfig分支metabase-embediframe 标签形态在 embed.ts 中以扁平字段instanceUrl、jwtProviderUri、fetchRequestToken、preferredAuthMethod表达同样的语义注意字段名差异metabaseInstanceUrlvsinstanceUrl。访客嵌入isGuest: true不走本类型它属于MetabaseIsGuestAuthConfig分支使用guestEmbedProviderUri而非jwtProviderUri。小结MetabaseAuthConfigWithJwt用一个 TypeScript 交叉类型把 JWT 嵌入认证的三种可选能力——jwtProviderUri直连取 token、跳过 discovery、fetchRequestToken自定义取 token、preferredAuthMethodSAML/JWT 共存时的显式选择——与必填的metabaseInstanceUrl组合在一起并用never字段与其他认证分支划清边界。源码层面的证据链清晰类型定义在 auth-config.ts取 token 与交换会话的 HTTP 流程在 jwt.ts提前认证与会话刷新入口分别在 bootstrap-auth.ts 和 auth.ts。沿着这几处文件可以完整复现从宿主应用 JWT 到 Metabase 会话令牌的全链路。【免费下载链接】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），仅供参考