令牌机制全解析Convex Better Auth 如何用 JWT JWKS 验证每一次请求【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth在搭建现代全栈应用时认证与授权是绕不开的难题。GitHub 加速计划中的con / better-auth项目将 Convex 与 Better Auth 无缝结合用一套完整的令牌机制——JWT签发与JWKS公钥验证——为每一次 API 请求保驾护航。无论你是刚接触认证体系的新手还是想深入理解令牌验证原理的进阶开发者这篇文章都会带你快速吃透令牌从哪来、如何签发、Convex 又是怎样用 JWKS 验证它的。为什么需要令牌机制从 Session 到 JWT 的演进传统 Web 应用靠 Session会话识别用户服务端保存会话数据客户端保存 Session ID。这套方案在单体应用里够用但在 Serverless、边缘计算和前后端分离的架构下Session 的有状态特性成了负担——每次请求都要查库横向扩容还要同步会话数据。令牌机制Token的出现就是为了解决这个问题。Better Auth 签发的 JWT 令牌是自包含的用户信息、过期时间、签发方全都编码在令牌里服务端无需查库即可验明正身。Convex 作为实时后端天然适合与这种无状态 可验证的令牌机制配合。一文读懂 JWT三段式令牌结构JWTJSON Web Token看起来是一长串乱码实际由三部分组成用点号分隔Header头部声明令牌类型和签名算法例如EdDSA或RS256。Payload载荷携带用户 ID、会话 ID、签发时间iat、过期时间等声明。Signature签名用私钥对前两部分签名防止令牌被篡改。在 con / better-auth 的 Convex 插件中签发逻辑集中在src/plugins/convex/index.ts。JWT 的默认过期时间为15 分钟jwtExpirationSeconds默认值为60 * 15令牌的issuer指向你的 Convex 站点地址audience固定为convex而sessionId和iat会被自动注入载荷。小知识过期时间短并不代表体验差。Better Auth 还有独立的会话机制兜底JWT 只负责短时验证即使令牌泄露影响窗口也被压缩到最小。JWKS 是什么公钥池如何参与令牌验证JWT 的签名需要用私钥生成、公钥验证。私钥绝不能暴露而公钥可以公开分享。JWKSJSON Web Key Set就是存放这些公钥的公开钥匙串里面每把钥匙都有自己的 IDkid、算法alg和密钥类型kty。验证流程可以概括为四步收到请求中的 JWT 令牌从令牌 Header 中读取kid访问 JWKS 端点按kid找到对应的公钥用该公钥校验签名签名合法则信任令牌内容。在 con / better-auth 中JWKS 端点路径为/api/auth/convex/jwks公开公钥的组装逻辑见src/auth-config.ts中的createPublicJwks函数。它还提供了标准的 OpenID 配置端点/api/auth/convex/.well-known/openid-configuration方便 Convex 服务端自动发现jwks_uri。Convex 验证 JWT 的完整请求链路现在把整个过程串起来看看一次请求如何被验证第一步登录签发令牌。用户通过邮箱密码、OAuth 回调、魔法链接等任意方式登录后Better Auth 会同步生成 JWT并通过名为convex_jwt的 Cookie 下发到浏览器。这个登录后自动签发的逻辑位于src/plugins/convex/index.ts的after钩子中覆盖/sign-in、/sign-up、/callback、/magic-link/verify等全部登录入口登出或删除账号时同一钩子负责清空令牌。第二步前端携带令牌。浏览器后续发起的每次请求都会自动带上convex_jwtCookie。第三步Convex 校验令牌。Convex 服务端通过convex/auth.config.ts中声明的认证提供方customJwt类型获取 JWKS 并验证签名。示例配置见examples/next/convex/auth.config.tsexport default { providers: [getAuthConfigProvider()], } satisfies AuthConfig;第四步通过校验进入业务逻辑。令牌验证通过后Convex 才把请求放行到你的查询query或变更mutation函数中你无需在每个函数里重复鉴权。想要边跑边看效果可以参照示例工程examples/next/convex/auth.ts其中getCurrentUser就是一个最简的取当前用户查询示例。密钥轮换rotateKeys 让令牌机制更安全任何长期不换的密钥都有被攻破的风险因此密钥轮换Key Rotation是令牌机制的必备安全实践。con / better-auth 提供了现成的轮换接口rotateKeys它会清空旧的 JWKS 记录并重新生成一套全新的公钥/私钥对。在示例工程examples/next/convex/auth.ts中已经内置了轮换用的内部 ActionrotateKeys你可以按需定期执行。轮换后旧令牌会立即失效从机制上杜绝了旧令牌长期有效的隐患。静态 JWKS为令牌验证提速的优化技巧默认情况下Convex 每次验证令牌都要访问 JWKS 端点拉取公钥这会多一次网络请求。con / better-auth 提供了静态 JWKS优化方案把公钥集合提前内嵌到配置里验证时完全无需联网。具体做法是先运行一次轮换或生成命令拿到 JWKS 文档再把它写入环境变量JWKS最后在getAuthConfigProvider和 Convex 插件中分别传入npx convex run auth:rotateKeys | npx convex env set JWKSexamples/next/convex/auth.config.tsgetAuthConfigProvider({ jwks: process.env.JWKS })examples/next/convex/auth.tsconvex({ authConfig, jwks: process.env.JWKS })需要提醒的是使用静态 JWKS 后轮换密钥时需要同步更新环境变量否则会出现签名验证失败。如果你升级了 Convex 或 Better Auth 版本导致算法不匹配也可以临时开启jwksRotateOnTokenGenerationError让插件在签发令牌出错时自动轮换密钥这一配置同样在src/plugins/convex/index.ts中。常见问题与排错思路1. 令牌验证失败 / 401 频繁出现优先检查客户端与服务端的JWKS环境变量是否一致尤其是在开启静态 JWKS 后。2. 升级版本后令牌报错关注算法是否从EdDSA切换到了RS256customJwt提供方强制使用 RS256。若现有 JWKS 中的密钥与算法不匹配可开启jwksRotateOnTokenGenerationError自动处理。3. 登录后页面仍显示未登录检查convex_jwtCookie 是否成功写入以及它的过期时间默认 15 分钟是否与你的使用场景匹配可通过jwt.expirationSeconds调整。4. 想自定义令牌内容使用jwt.definePayload在签发时注入自定义字段sessionId和iat会自动追加无需手工处理。小结con / better-auth 用一套清晰的令牌机制把 JWT 签发、JWKS 公钥验证、密钥轮换和静态 JWKS 优化串成了完整的闭环Better Auth 负责签Convex 负责验开发者只需几行配置就能享受企业级的请求鉴权。如果你想亲手体验完整流程可以克隆这个项目并运行examples/next示例登录、签发、验证、轮换一条龙跑通相信你会对 JWT JWKS 的协作方式有更直观的理解。【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
令牌机制全解析：Convex + Better Auth 如何用 JWT + JWKS 验证每一次请求
令牌机制全解析Convex Better Auth 如何用 JWT JWKS 验证每一次请求【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth在搭建现代全栈应用时认证与授权是绕不开的难题。GitHub 加速计划中的con / better-auth项目将 Convex 与 Better Auth 无缝结合用一套完整的令牌机制——JWT签发与JWKS公钥验证——为每一次 API 请求保驾护航。无论你是刚接触认证体系的新手还是想深入理解令牌验证原理的进阶开发者这篇文章都会带你快速吃透令牌从哪来、如何签发、Convex 又是怎样用 JWKS 验证它的。为什么需要令牌机制从 Session 到 JWT 的演进传统 Web 应用靠 Session会话识别用户服务端保存会话数据客户端保存 Session ID。这套方案在单体应用里够用但在 Serverless、边缘计算和前后端分离的架构下Session 的有状态特性成了负担——每次请求都要查库横向扩容还要同步会话数据。令牌机制Token的出现就是为了解决这个问题。Better Auth 签发的 JWT 令牌是自包含的用户信息、过期时间、签发方全都编码在令牌里服务端无需查库即可验明正身。Convex 作为实时后端天然适合与这种无状态 可验证的令牌机制配合。一文读懂 JWT三段式令牌结构JWTJSON Web Token看起来是一长串乱码实际由三部分组成用点号分隔Header头部声明令牌类型和签名算法例如EdDSA或RS256。Payload载荷携带用户 ID、会话 ID、签发时间iat、过期时间等声明。Signature签名用私钥对前两部分签名防止令牌被篡改。在 con / better-auth 的 Convex 插件中签发逻辑集中在src/plugins/convex/index.ts。JWT 的默认过期时间为15 分钟jwtExpirationSeconds默认值为60 * 15令牌的issuer指向你的 Convex 站点地址audience固定为convex而sessionId和iat会被自动注入载荷。小知识过期时间短并不代表体验差。Better Auth 还有独立的会话机制兜底JWT 只负责短时验证即使令牌泄露影响窗口也被压缩到最小。JWKS 是什么公钥池如何参与令牌验证JWT 的签名需要用私钥生成、公钥验证。私钥绝不能暴露而公钥可以公开分享。JWKSJSON Web Key Set就是存放这些公钥的公开钥匙串里面每把钥匙都有自己的 IDkid、算法alg和密钥类型kty。验证流程可以概括为四步收到请求中的 JWT 令牌从令牌 Header 中读取kid访问 JWKS 端点按kid找到对应的公钥用该公钥校验签名签名合法则信任令牌内容。在 con / better-auth 中JWKS 端点路径为/api/auth/convex/jwks公开公钥的组装逻辑见src/auth-config.ts中的createPublicJwks函数。它还提供了标准的 OpenID 配置端点/api/auth/convex/.well-known/openid-configuration方便 Convex 服务端自动发现jwks_uri。Convex 验证 JWT 的完整请求链路现在把整个过程串起来看看一次请求如何被验证第一步登录签发令牌。用户通过邮箱密码、OAuth 回调、魔法链接等任意方式登录后Better Auth 会同步生成 JWT并通过名为convex_jwt的 Cookie 下发到浏览器。这个登录后自动签发的逻辑位于src/plugins/convex/index.ts的after钩子中覆盖/sign-in、/sign-up、/callback、/magic-link/verify等全部登录入口登出或删除账号时同一钩子负责清空令牌。第二步前端携带令牌。浏览器后续发起的每次请求都会自动带上convex_jwtCookie。第三步Convex 校验令牌。Convex 服务端通过convex/auth.config.ts中声明的认证提供方customJwt类型获取 JWKS 并验证签名。示例配置见examples/next/convex/auth.config.tsexport default { providers: [getAuthConfigProvider()], } satisfies AuthConfig;第四步通过校验进入业务逻辑。令牌验证通过后Convex 才把请求放行到你的查询query或变更mutation函数中你无需在每个函数里重复鉴权。想要边跑边看效果可以参照示例工程examples/next/convex/auth.ts其中getCurrentUser就是一个最简的取当前用户查询示例。密钥轮换rotateKeys 让令牌机制更安全任何长期不换的密钥都有被攻破的风险因此密钥轮换Key Rotation是令牌机制的必备安全实践。con / better-auth 提供了现成的轮换接口rotateKeys它会清空旧的 JWKS 记录并重新生成一套全新的公钥/私钥对。在示例工程examples/next/convex/auth.ts中已经内置了轮换用的内部 ActionrotateKeys你可以按需定期执行。轮换后旧令牌会立即失效从机制上杜绝了旧令牌长期有效的隐患。静态 JWKS为令牌验证提速的优化技巧默认情况下Convex 每次验证令牌都要访问 JWKS 端点拉取公钥这会多一次网络请求。con / better-auth 提供了静态 JWKS优化方案把公钥集合提前内嵌到配置里验证时完全无需联网。具体做法是先运行一次轮换或生成命令拿到 JWKS 文档再把它写入环境变量JWKS最后在getAuthConfigProvider和 Convex 插件中分别传入npx convex run auth:rotateKeys | npx convex env set JWKSexamples/next/convex/auth.config.tsgetAuthConfigProvider({ jwks: process.env.JWKS })examples/next/convex/auth.tsconvex({ authConfig, jwks: process.env.JWKS })需要提醒的是使用静态 JWKS 后轮换密钥时需要同步更新环境变量否则会出现签名验证失败。如果你升级了 Convex 或 Better Auth 版本导致算法不匹配也可以临时开启jwksRotateOnTokenGenerationError让插件在签发令牌出错时自动轮换密钥这一配置同样在src/plugins/convex/index.ts中。常见问题与排错思路1. 令牌验证失败 / 401 频繁出现优先检查客户端与服务端的JWKS环境变量是否一致尤其是在开启静态 JWKS 后。2. 升级版本后令牌报错关注算法是否从EdDSA切换到了RS256customJwt提供方强制使用 RS256。若现有 JWKS 中的密钥与算法不匹配可开启jwksRotateOnTokenGenerationError自动处理。3. 登录后页面仍显示未登录检查convex_jwtCookie 是否成功写入以及它的过期时间默认 15 分钟是否与你的使用场景匹配可通过jwt.expirationSeconds调整。4. 想自定义令牌内容使用jwt.definePayload在签发时注入自定义字段sessionId和iat会自动追加无需手工处理。小结con / better-auth 用一套清晰的令牌机制把 JWT 签发、JWKS 公钥验证、密钥轮换和静态 JWKS 优化串成了完整的闭环Better Auth 负责签Convex 负责验开发者只需几行配置就能享受企业级的请求鉴权。如果你想亲手体验完整流程可以克隆这个项目并运行examples/next示例登录、签发、验证、轮换一条龙跑通相信你会对 JWT JWKS 的协作方式有更直观的理解。【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考