跨域认证实战：Convex + Better Auth cross-domain 插件如何实现 Cookie 跨域共享

跨域认证实战Convex Better Auth cross-domain 插件如何实现 Cookie 跨域共享【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth跨域认证一直是 Web 开发者绕不开的痛点当认证服务部署在auth.example.com业务应用跑在app.example.com时浏览器基于 SameSite 策略的 Cookie 机制会让登录状态无法在多个域名间共享。本篇文章将带你完整理解 Better Auth 的 cross-domain 跨域认证插件它正是为解决这类问题而生——通过自定义请求头与本地存储配合在 Convex Better Auth 的架构下优雅地实现 Cookie 跨域共享。什么是跨域认证难题为什么 Cookie 不能直接跨域绝大多数认证系统依赖 Cookie 保存会话。Cookie 默认绑定域名且现代浏览器普遍启用SameSiteLax甚至SameSiteStrict这意味着浏览器不会在跨站请求中自动携带 Cookie即使前端用 fetch 设置了credentials: include跨域场景下也会因 CORS 与 SameSite 双重限制而失败二级域名不同如a.com与b.com也无法靠Domain属性打通。所以当你的 Convex 后端、认证服务与前端站点分属不同域名时登录状态就断了——这就是跨域认证要解决的核心问题。Better Auth cross-domain 插件的核心思路用请求头替代 CookieBetter Auth 的 cross-domain 插件源码位于 src/plugins/cross-domain/index.ts采用的方案非常巧妙不试图让 Cookie 直接跨域而是把会话令牌存到浏览器本地存储localStorage再通过自定义请求头发送给服务端。浏览器 localStorage ──► Better-Auth-Cookie 请求头 ──► 认证服务 ▲ │ └────────── Set-Better-Auth-Cookie 响应头 ◄──────────┘服务端在收到自定义请求头后会把它翻译成标准的 Cookie 处理逻辑返回时则把Set-Cookie改写为Set-Better-Auth-Cookie响应头由客户端插件负责持久化到本地存储。三步搞定服务端配置在 Convex 中启用 cross-domain 插件以项目中的 examples/react/convex/auth.ts 为例配置非常简单第一步设置站点 URL 环境变量在convex/auth.ts顶部定义你的主站地址const siteUrl process.env.SITE_URL!;第二步在插件列表中加入 crossDomainplugins: [ magicLink({ ... }), emailOTP({ ... }), crossDomain({ siteUrl }), convex({ authConfig }), ],第三步配置 trustedOrigins插件初始化时会自动把siteUrl加入trustedOrigins你只需在betterAuth()配置中确认可信来源即可trustedOrigins: [siteUrl],图示Convex Better Auth 全家桶cross-domain 插件正是为多域名部署设计的跨域认证组件。前端配置crossDomainClient 让 Cookie 跨域共享自动发生前端只需在createAuthClient中引入crossDomainClient参考 examples/react/src/lib/auth-client.tsimport { createAuthClient } from better-auth/react; import { convexClient, crossDomainClient } from convex-dev/better-auth/client/plugins; export const authClient createAuthClient({ baseURL: import.meta.env.VITE_CONVEX_SITE_URL, plugins: [magicLinkClient(), emailOTPClient(), crossDomainClient(), convexClient()], });crossDomainClient客户端插件源码位于 src/plugins/cross-domain/client.ts会自动完成三件事存储拦截Set-Better-Auth-Cookie响应头把 Cookie 序列化后写入localStorage键名为better-auth_cookie发送每次请求前读取存储的 Cookie拼进Better-Auth-Cookie请求头并设置credentials: omit避免浏览器自动带 Cookie 造成干扰同步当会话令牌真正变化时才触发updateSession避免无效轮询。会话如何在两个域名间握手一次完整的登录流程以邮件魔法链接登录为例跨域认证的完整链路是用户在app.example.com点击登录向认证服务发起sign-in/magic-link请求服务端插件自动把callbackURL改写为主站地址siteUrl邮件中的链接指向主站用户点击邮件链接完成验证服务端在/callback等路径生成一次性令牌one-time token并重定向到主站主站拿到令牌后调用/cross-domain/one-time-token/verify端点兑换真实会话服务端通过Set-Better-Auth-Cookie返回会话 Cookie客户端插件存入localStorage之后所有跨域请求都通过Better-Auth-Cookie请求头携带会话Cookie 跨域共享就此打通。它如何保证跨域认证的安全性跨域认证方案最容易被质疑的是安全性cross-domain 插件在几个关键点做了防护一次性令牌机制会话不是直接暴露在 URL 中而是通过 3 分钟有效期的 one-time token 兑换令牌只能使用一次见 src/plugins/cross-domain/index.ts 中的verifyOneTimeToken端点状态码校验OAuth 流程将 state 存入数据库并跳过 Cookie 校验但仍严格比对 query string 中的 state 与数据库记录令牌校验优先请求若携带Authorization头则跳过 Cookie 注入逻辑避免双重身份凭证冲突过期清理客户端存储 Cookie 时会记录过期时间取出时自动过滤已过期的令牌。什么时候适合使用 cross-domain 插件如果你的项目满足以下任一场景cross-domain 插件就非常合适✅ 认证服务与业务前端部署在不同域名✅ 使用 Convex 作为后端希望通过 Better Auth 统一管理多端登录态✅ 前端是 SPAReact、Vue、TanStack 等无 SSR 强需求✅ 希望兼容 Expo 等原生环境插件对expo-origin请求头有专门的跳过逻辑。总结跨域认证不需要牺牲安全来换取便利。Better Auth 的 cross-domain 插件用本地存储 自定义请求头 一次性令牌的组合拳在 Convex 架构下实现了既安全又无感的Cookie 跨域共享。只需一个crossDomain({ siteUrl })服务端插件加一个crossDomainClient()客户端插件就能打通多个域名之间的登录态让用户在一次登录后无缝穿梭于你的所有应用。如果你想在本地体验完整效果可以参考仓库中的 examples/react 示例快速跑起一套多域名认证环境。【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考