在 Convex 中接入 Auth0 认证：从 Auth0 CLI 快速搭建到 Convex 后端验签的完整指南

数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载导读本指南围绕 Convex 开源仓库中 Auth0 认证接入的完整方案展开覆盖Auth0 应用创建CLI 或 Dashboard 两条路径→convex/auth.config.ts服务端配置 → 前后端环境变量 →Auth0ProviderConvexProviderWithAuth0前端接线 → 用 Convex 认证状态门控 UI → 本地/生产双租户 → 验证与排障的全流程。读完本文你将掌握如何用 Auth0 CLI 把机械化的应用创建自动化掉、如何让 Convex 后端独立校验 Auth0 签发的 JWT、为什么Auth0 登录成功不等于Convex 认证通过以及当 refresh token 流程报Unknown or invalid refresh token时该如何止损。背景为什么要在 Convex 项目里接入 Auth0Auth0 是一个成熟的认证平台提供密码登录、社交身份提供商Google、GitHub 等登录、一次性邮箱/短信验证码、多因素认证MFA、单点登录SSO以及基础用户管理能力。对于已经使用 Auth0、或明确指定要使用 Auth0 的 Convex 应用将其作为认证层接入是最自然的选择。在 Convex 的认证模型中认证与授权是解耦的Auth0 负责确认你是谁签发 JWTConvex 负责验证你带来的 token 是否可信服务端校验签名与 audience并给出UserIdentity。因此整个接入工作可以分为两个互相独立、缺一不可的环节Auth0 侧创建 Auth0 应用、配置回调地址、让用户完成登录Convex 侧在convex/auth.config.ts中登记 Auth0 的domain与applicationID让后端能够校验 Auth0 签发的 token。参考官方文档见 npm-packages/docs/docs/auth/auth0.mdx本文以该指南与 npm-packages/private-demos/waitlist/.claude/skills/convex-setup-auth/references/auth0.md下文简称技能参考文档为骨架展开。接入前的决策点动手之前技能参考文档明确要求先确认三件事确认用户确实想要 Auth0而不是其他认证方案确认应用的技术栈React / Next.js / Vite 等以及 Auth0 是否已经部分接入——如果仓库里已经有 Auth0 配置务必保留既有的 redirect 与 tenant 配置除非用户明确要求改动确认本次只做本地local-only还是要做生产就绪production-ready这决定了后续是只配置 dev tenant还是 dev/prod 双 tenant 都要覆盖。此外还要决定走哪条创建路径Auth0 CLI 路径最快适合从零开始的新项目。先安装 Auth0 CLI用户执行一次auth0 login完成 CLI 与自身 Auth0 tenant 的绑定之后应用创建、回调 URL 配置等机械操作都可以自动化完成Dashboard 路径不安装任何额外工具在 Auth0 控制台手动创建应用适合不愿意安装 CLI 或已有存量应用的场景。技能参考文档特别强调不要假装 refresh-token 路径已经被完整验证。仓库内的验证记录显示useRefreshTokens{true}配合cacheLocationlocalstorage的官方推荐配置在实际验证中曾触发 refresh-token 失败因此该路径目前仍标记为under investigation遇到相关报错时应明确告知用户并引导回官方文档而不是无限自行修补。第一条路径用 Auth0 CLI 快速创建应用如果用户同意安装 Auth0 CLI按以下步骤执行Auth0 CLI 的安装与命令参考见其官方文档auth0-apps-create页面# 1. 安装并登录登录需要用户本人的 Auth0 账号交互 auth0 login # 2. 创建 SPA 应用指定应用类型、回调地址、登出地址与 Web 来源 auth0 apps create \ --type spa \ --callback-urls http://localhost:5173/callback \ --logout-urls http://localhost:5173 \ --web-origins http://localhost:5173创建完成后从 CLI 输出中取回两项关键信息Auth0 domain形如your-domain.us.auth0.com和client ID。它们将同时用于后端auth.config.ts与前端Auth0Provider。需要特别注意的是CLI 路径虽然快但仍然要求用户先把 CLI 认证到自己的 Auth0 tenant并且 CLI 产出的只是 Auth0 应用侧的配置Convex 侧的接线仍然需要手工完成。技能参考文档的定位是优先 CLI 做机械搭建但不要把该路径描述为端到端已验证。第二条路径Auth0 Dashboard 手动创建不走 CLI 时按 Auth0 官方 React Quickstart 在 Dashboard 中创建应用注册免费 Auth0 账号并创建 tenant在 Dashboard 的 Applications 中新建Single Page ApplicationSPA配置回调地址Callback URLs、登出地址Logout URLs与 Allowed Web Origins。官方文档给出的本地开发示例值为http://localhost:3000, http://localhost:5173具体以你本地实际运行的端口为准——回调/登出/Web Origins 必须与开发服务器真实端口完全一致否则登录跳转会失败完成 Auth0 React Quickstart 中Install the Auth0 React SDK这一步后即可回到 Convex 侧接线。技能参考文档的 Gotchas 提醒Convex 官方文档默认 Auth0 侧已经就绪所以从零开始的项目不要跳过 Auth0 quickstart同时不要想当然地认为本地 tenant 的配置与生产一致生产环境的 domain、client ID 和回调 URL 都需要单独核实。配置 Convex 后端convex/auth.config.ts在项目convex/目录下创建auth.config.ts把 Auth0 的 domain 与 client ID 填入import { AuthConfig } from convex/server; export default { providers: [ { domain: your-domain.us.auth0.com, applicationID: yourclientid, }, ] } satisfies AuthConfig;从源码看AuthConfig与AuthProvider的类型定义位于 npm-packages/convex/src/server/authentication.tsproviders是允许为你的应用签发 JWT 的认证提供方列表OIDC 提供方Auth0 属于此类需要domainOIDC 提供方的域名与applicationID后端校验时要求token 的 audience 中包含该applicationIDapplicationID匹配不上会导致认证失败除 OIDC 外该类型还支持customJwt提供方需配置issuer、jwks地址与RS256/ES256签名算法Auth0 接入不需要用到。关键操作修改auth.config.ts后必须重新同步到后端否则后端仍按旧配置校验npx convex dev # 本地开发自动同步配置到后端生产环境则使用npx convex deploy。前端接线Auth0Provider 与 ConvexProviderWithAuth0前端需要安装 Auth0 SDKReact 项目为auth0/auth0-react然后把原本的ConvexProvider替换为「Auth0Provider包裹ConvexProviderWithAuth0」的结构。ConvexProviderWithAuth0的完整实现位于 npm-packages/convex/src/react-auth0/ConvexProviderWithAuth0.tsx源码揭示了几点关键事实它内部通过useAuth0()取得isLoading、isAuthenticated与getAccessTokenSilently取 token 时调用getAccessTokenSilently({ detailedResponse: true, cacheMode: forceRefreshToken ? off : on })并返回id_token而非 access token——Convex 用它作为 JWT 交给后端验签它基于通用的 npm-packages/convex/src/react/ConvexAuthState.tsx 中的ConvexProviderWithAuth实现认证状态由Auth0 前端状态与Convex 后端确认结果双重决定——isAuthenticated authProviderAuthenticated (isConvexAuthenticated ?? false)即只有 Auth0 已登录且 Convex 后端确认 token 有效才算真正认证通过useConvexAuth()会返回isLoading/isAuthenticated/isRefreshing三个状态其中isRefreshing表示后端拒绝了此前已确认的 token、socket 暂停等待新 token仅在isAuthenticated为 true 时可能出现。仓库中的真实示例npm-packages/private-demos/quickstarts/react-vite-ts/src/_mainAuth0.tsx展示了完整的接线方式import React from react; import ReactDOM from react-dom/client; import App from ./App; import ./index.css; import { ConvexReactClient } from convex/react; import { ConvexProviderWithAuth0 } from convex/react-auth0; import { Auth0Provider } from auth0/auth0-react; const convex new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string); ReactDOM.createRoot(document.getElementById(root)!).render( React.StrictMode Auth0Provider domainyour-domain.us.auth0.com clientIdyourclientid authorizationParams{{ redirect_uri: window.location.origin, }} useRefreshTokens{true} cacheLocationlocalstorage ConvexProviderWithAuth0 client{convex} App / /ConvexProviderWithAuth0 /Auth0Provider /React.StrictMode, );需要说明的是useRefreshTokens{true}与cacheLocationlocalstorage是官方示例的推荐写法但按照技能参考文档的验证记录该 refresh-token 组合在实际验证中触发过失败详见验证与已知问题一节因此接入时如遇相关报错不应将其视为已定论的配置。登录、登出与用户信息登录与登出按钮登录与登出使用 Auth0 React SDK 的useAuth0()hookimport { useAuth0 } from auth0/auth0-react; export default function LoginButton() { const { loginWithRedirect } useAuth0(); return button onClick{loginWithRedirect}Log in/button; }loginWithRedirect会把用户重定向到 Auth0 Universal Login 页面登出则调用logout()重定向到 Auth0 登出端点。用 useConvexAuth 门控 Convex 相关 UI判断Convex 数据是否可安全展示时不要用useAuth0()要用useConvexAuth()它保证浏览器已经取到访问 Convex 后端所需的 tokenimport { useConvexAuth } from convex/react; function App() { const { isLoading, isAuthenticated } useConvexAuth(); return ( div classNameApp {isAuthenticated ? Logged in : Logged out or still loading} /div ); }也可以使用Authenticated、Unauthenticated、AuthLoading与AuthRefreshing四个声明式组件它们底层都基于useConvexAuth其中AuthRefreshing在查询/变更因 token 刷新被暂停时渲染通常是罕见场景import { Authenticated, Unauthenticated, AuthLoading, AuthRefreshing, } from convex/react; function App() { return ( div classNameApp AuthenticatedLogged in/Authenticated UnauthenticatedLogged out/Unauthenticated AuthLoadingStill loading/AuthLoading AuthRefreshingRefreshing token.../AuthRefreshing /div ); }展示用户信息前端展示用户昵称等信息直接用useAuth0()的user对象import { useAuth0 } from auth0/auth0-react; export default function Badge() { const { user } useAuth0(); return spanLogged in as {user.name}/span; }而后端函数query/mutation/action中获取用户身份则通过ctx.auth.getUserIdentity()——这是验证Convex 是否认可该 Auth0 会话的权威途径见下文验证。环境变量本地与生产分离后端环境变量把auth.config.ts改为读取环境变量即可在 dev / prod 之间切换不同 Auth0 tenantimport { AuthConfig } from convex/server; export default { providers: [ { domain: process.env.AUTH0_DOMAIN!, applicationID: process.env.AUTH0_CLIENT_ID!, }, ], } satisfies AuthConfig;本地开发在 Convex Dashboard 的 dev deployment Settings → Environment Variables 中添加AUTH0_DOMAIN与AUTH0_CLIENT_ID然后运行npx convex dev应用新配置生产在 Convex Dashboard 左侧菜单切换到生产 deployment设置生产 Auth0 tenant 对应的值然后运行npx convex deploy。前端环境变量客户端侧同样用环境变量注入变量名取决于前端平台Vite 使用VITE_前缀。本地开发写入.env.localVITE_AUTH0_DOMAINyour-domain.us.auth0.com VITE_AUTH0_CLIENT_IDyourclientid对应的Auth0Provider写法见仓库示例 npm-packages/private-demos/quickstarts/react-vite-ts/src/_mainAuth0Env.tsxAuth0Provider domain{import.meta.env.VITE_AUTH0_DOMAIN} clientId{import.meta.env.VITE_AUTH0_CLIENT_ID} authorizationParams{{ redirect_uri: window.location.origin, }} useRefreshTokens{true} cacheLocationlocalstorage ConvexProviderWithAuth0 client{convex} App / /ConvexProviderWithAuth0 /Auth0Provider生产环境则在你的托管平台上设置同名变量。技能参考文档总结的常见环境变量集为变量用途AUTH0_DOMAIN/AUTH0_CLIENT_IDConvex 后端读取写入 Convex Dashboard 环境变量VITE_AUTH0_DOMAIN/VITE_AUTH0_CLIENT_IDVite 前端读取其他框架前缀不同写入.env.local或托管平台保持 dev 与 prod tenant 分离如果项目在不同环境使用不同的 Auth0 tenant务必确认生产 domain、client ID、回调 URL 各自独立配置不要默认本地 tenant 设置与生产一致。验证Auth0 登录成功 ≠ Convex 认证通过技能参考文档的 Validation 章节给出了一套完整的验收清单用户能完整走完 Auth0 登录流程登录 → 重定向回应用Convex 认证状态的 UI 仅在useConvexAuth()的 auth state ready 后才渲染登录后受保护的 Convex query 能正常执行后端受保护函数中ctx.auth.getUserIdentity()返回非null开发期间 Auth0 应用设置与真实本地回调/登出 URL 一致若请求了生产就绪配置生产 Auth0 配置也已覆盖。其中最关键的一条是后端视角的确认ctx.auth.getUserIdentity()非空才意味着 Convex 后端真正验证了 Auth0 签发的 JWT签名、issuer、audience 均通过。技能参考文档特别警告Auth0 登录成功与Convex 能验证 Auth0 token是两件不同的事二者都必须成立——Auth0 侧成功只代表用户拿到了 Auth0 的会话Convex 侧还需要 token 通过后端校验。调试登录成功但 isAuthenticated 为 false如果用户走完 Auth0 登录、重定向回页面后useConvexAuth()仍返回isAuthenticated: false按以下顺序排查检查convex/auth.config.tsdomain与applicationID是否与 Auth0 应用设置完全一致domain 形如your-domain.us.auth0.comclient ID 可在 Auth0 Dashboard 的 Application Settings 中查到确认后端配置已同步auth.config.ts的providers列表必须通过npx convex dev本地或npx convex deploy生产同步到后端只改文件不运行命令不会生效检查前端Auth0Provider的domain/clientId是否与后端配置一致避免出现前端用 dev tenant、后端用 prod tenant 的错配确认本地回调 URL、登出 URL、Web Origins 与实际端口匹配。更深入的排查步骤可参考仓库文档 npm-packages/docs/docs/auth/debug.mdx。已知问题与诚实边界技能参考文档在 Gotchas 中记录了几条尚未完全验证的边界接入时务必知情refresh-token 路径未端到端验证文档推荐并验证过的useRefreshTokens{true}cacheLocationlocalstorage组合曾触发 refresh-token 失败因此不要将该路径描述为已定论若遇到Unknown or invalid refresh token之类的 Auth0 报错不要无限编造修复方案应停止并向用户说明该路径仍在调查中引导回官方文档CLI 路径未完全验证Auth0 CLI 可以自动化应用创建与 Convex 配置接线但它要求用户先将 CLI 认证到自己的 tenant且该路径同样没有完成 refresh-token 的端到端验证不要把能登录当已验证只有用户能登录且Convex 识别该认证会话getUserIdentity()非空时才能宣称接入成功否则应如实标注该路径仍在调查中不要默认向仓库写笔记文件如用户需要 rollout 或交接文档应显式创建而不是默认把 notes 文件静默写进仓库。生产就绪收尾如果用户要求 production-ready 配置最终验收前确认生产 Auth0 tenant 的值domain、client ID已配置到生产 Convex deployment 的环境变量生产 Auth0 应用的回调 URL、登出 URL 与 Web Origins 指向真实生产域名生产环境变量与重定向设置均已核实再宣布任务完成。完整检查清单确认用户确实想要 Auth0确认本地优先还是生产就绪完成对应框架的 Auth0 前端 quickstart从零开始的项目不可跳过配置convex/auth.config.tsdomain applicationID运行npx convex dev/npx convex deploy同步后端配置设置前后端环境变量AUTH0_DOMAIN、AUTH0_CLIENT_ID、VITE_AUTH0_DOMAIN、VITE_AUTH0_CLIENT_ID等用Auth0Provider包裹ConvexProviderWithAuth0用useConvexAuth()/Authenticated等门控 Convex UI登录后验证useConvexAuth()为 authenticated且后端ctx.auth.getUserIdentity()非空否则明确告知该路径仍在调查中并引导官方文档如请求了生产配置确认生产 tenant 与部署配置也已覆盖参考源码与文档索引官方 Auth0 接入指南npm-packages/docs/docs/auth/auth0.mdx前端适配组件实现npm-packages/convex/src/react-auth0/ConvexProviderWithAuth0.tsx通用认证状态机制npm-packages/convex/src/react/ConvexAuthState.tsx后端配置类型定义AuthConfig/AuthProvider/UserIdentitynpm-packages/convex/src/server/authentication.ts硬编码配置示例npm-packages/private-demos/quickstarts/react-vite-ts/src/_mainAuth0.tsx环境变量配置示例npm-packages/private-demos/quickstarts/react-vite-ts/src/_mainAuth0Env.tsx认证调试指南npm-packages/docs/docs/auth/debug.mdx赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐Convex 接入 Auth0 认证完全指南从 CLI 自动化、auth.config.ts 到生产就绪部署Convex 接入 Auth0 认证完全指南从 CLI 自动化、auth.config.ts 到生产就绪部署 本篇指南围绕 convex backend 仓库数据库后端Convex 集成 Auth0 认证完全指南从 auth.config.ts 到 ConvexProviderWithAuth0 的接入、验证与生产配置Convex 集成 Auth0 认证完全指南从 auth.config.ts 到 ConvexProviderWithAuth0 的接入、验证与生产配置 本文数据库后端Convex Auth在 Convex 后端直接落地的完整认证接入指南convex-backend 仓库实战Convex Auth在 Convex 后端直接落地的完整认证接入指南convex backend 仓库实战 Convex Auth 是 Convex 官数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考