数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载本文基于 convex-backend 仓库中 SvelteKit 快速开始项目的 convex-setup-auth 技能参考文档 编写系统讲解在 Convex 应用中接入 Auth0 认证的完整流程。读完本文你将掌握如何在已有或全新 Auth0 租户上创建 SPA 应用、如何配置convex/auth.config.ts让 Convex 校验 Auth0 签发的 JWT、如何用Auth0Provider与ConvexProviderWithAuth0完成前后端接线、如何用ctx.auth.getUserIdentity()保护后端函数以及如何区分Auth0 登录成功与Convex 识别会话成功这两个关键验证点。适用场景与前置判断Auth0 集成并非 Convex 认证的唯一选项动手前必须先确认选型。根据技能文档的指引Convex 支持多种认证方案Convex Auth希望认证逻辑完全由 Convex 托管时的默认选择Clerk应用已使用 Clerk 或需要 Clerk 托管认证能力WorkOS AuthKit应用已使用 WorkOS 或指定 AuthKitAuth0应用已经使用 Auth0或用户明确指定 Auth0本文主题自定义 JWT 提供方集成上述之外已有的认证系统。判断依据可以从仓库中已有的痕迹获得依赖包如auth0/*、clerk/*、已有文件如convex/auth.config.ts、auth 中间件、provider 包装组件或登录组件、指向特定提供方的环境变量。只有当仓库已使用 Auth0 或用户明确选择 Auth0 时才走本文的 Auth0 路径。此外在动手前必须确认两个关键问题应用框架与 Auth0 现状应用是 React、Next.js 还是 SvelteKitAuth0 是否已部分接入目标范围用户需要 local-only 开发环境配置还是 production-ready 生产配置这决定了后续租户、回调地址与环境变量的覆盖范围。两条设置路径Auth0 CLI 与 Dashboard原文档给出了两条并行的 Auth0 应用创建路径核心取舍是速度与可控性。路径一Auth0 CLI最快路径如果用户愿意安装 Auth0 CLI可以用它完成绝大多数机械性设置安装 Auth0 CLI用户执行auth0 login完成 CLI 与 Auth0 租户的认证这是唯一必须由用户完成的人工步骤若创建新应用使用auth0 apps create并指定 SPA 类型同时配置 callback URL回调地址、logout URL登出地址与 web origins允许的 Web 来源从 CLI 输出中获取 Auth0 domain 与 client ID。文档明确提醒CLI 路径虽快但尚未被验证为完全端到端可用的路径not a fully validated end-to-end path yet尤其 refresh-token刷新令牌链路在验证中曾出现失败因此不应把这条路径描述为已经彻底跑通。路径二Auth0 Dashboard手动路径若用户不愿安装 CLI则按框架完成 Auth0 前端 quickstart并在 Dashboard 中手动创建 Auth0 应用随后从 Dashboard 获取 domain 与 client ID。无论走哪条路径拿到Auth0 domain形如your-tenant.auth0.com与client ID都是后续所有配置的前提。安装框架对应的 Auth0 SDK前端接线的前提是为应用框架安装 Auth0 SDK。对于 React 生态是auth0/auth0-react其他框架如 SvelteKit、Next.js、Vue应遵循各自框架的 Auth0 quickstart 选择对应 SDK。仓库中可找到 React 生态的接入示例例如 react-vite-ts 快速开始的 Auth0 接线文件 与 ConvexProviderWithAuth0 官方实现。文档特别强调Convex 官方 Auth0 文档假设 Auth0 侧已经设置完成因此如果应用是从零开始不要跳过 Auth0 前端 quickstart否则后续登录流程必然失败。后端配置convex/auth.config.tsconvex/auth.config.ts是 Convex 校验第三方 JWT 的入口文件位于项目根目录的convex/目录下。它导出一个满足AuthConfig类型的默认对象。从仓库源码 server/authentication.ts 可以看到该类型的真实定义export type AuthConfig { providers: AuthProvider[]; };其中AuthProvider是联合类型Auth0 属于OIDC provider分支只需要两个字段domainOIDC 提供方Auth0 租户的域名对应 Auth0 的AUTH0_DOMAINapplicationID令牌token中audience受众必须包含的应用 ID对应 Auth0 的 client ID。因此典型的 Auth0 配置形如import { AuthConfig } from convex/server; export default { providers: [ { domain: https://your-tenant.auth0.com, applicationID: your-auth0-client-id, }, ], } satisfies AuthConfig;关键点是domain 与 applicationID 必须与 Auth0 应用完全一致。文档的 Gotchas 中特别指出如果登录成功但 Convex 仍报告未认证请双重检查convex/auth.config.ts以及后端配置是否已同步——即修改该文件后必须运行正常的 Convex dev 或 deploy 流程让后端加载新配置例如npx convex dev或npx convex deploy否则 Convex 后端仍在使用旧配置校验令牌。环境变量本地与生产Auth0 集成涉及前端与后端两组环境变量文档列出的常见变量包括变量用途典型场景AUTH0_DOMAINAuth0 租户域名后端 / 服务端配置AUTH0_CLIENT_IDAuth0 应用客户端 ID后端 / 服务端配置VITE_AUTH0_DOMAIN暴露给前端构建的域名Vite 系前端VITE_前缀变量会打入前端包VITE_AUTH0_CLIENT_ID暴露给前端构建的客户端 IDVite 系前端对于 SvelteKit 应用前端环境变量通常以PUBLIC_前缀暴露例如在 SvelteKit 快速开始的 layout.svelte 中可以看到PUBLIC_CONVEX_URL通过$env/static/public导入的用法Auth0 的前端变量应遵循同样的公共变量暴露方式。文档强调三点dev 与 prod 环境分离如果项目使用不同的 Auth0 环境请保持开发租户与生产租户分开不要假设本地租户配置与生产一致生产环境的 domain、client ID 和回调地址必须单独核验本地回调地址必须匹配真实端口开发时 Auth0 应用设置中的 callback URL、logout URL 与 web origins 必须与应用实际监听的本地端口一致否则回调会被 Auth0 拒绝存量应用保持现状如果仓库已经使用 Auth0保留既有 redirect 与租户配置除非用户明确要求更改。前端接线Auth0Provider ConvexProviderWithAuth0完成 SDK 安装与 Auth0 应用创建后需要在应用入口处完成两层 Provider 嵌套。第一层Auth0Provider来自 Auth0 SDK负责 Auth0 登录态管理传入 Auth0 域名与客户端 IDimport { Auth0Provider } from auth0/auth0-react; Auth0Provider domain{AUTH0_DOMAIN} clientId{AUTH0_CLIENT_ID} authorizationParams{{ redirect_uri: window.location.origin, }} {/* 应用内容 */} /Auth0Provider第二层ConvexProviderWithAuth0来自convex/react负责把 Auth0 的登录态桥接到 Convex 客户端。查看仓库中的 ConvexProviderWithAuth0.tsx 实现可以看到它的核心机制它内部调用useAuth0()获取isLoading、isAuthenticated与getAccessTokenSilently通过fetchAccessToken回调在 Convex 每次需要令牌时调用getAccessTokenSilently({ detailedResponse: true, cacheMode: ... })并把返回的id_token而非 access token交给 ConvexforceRefreshToken为 true 时以cacheMode: off强制刷新令牌否则使用缓存令牌获取失败时返回null从而让 Convex 判定为未认证。典型接线方式是把原先的纯ConvexProvider替换为ConvexProviderWithAuth0并让ConvexProviderWithAuth0嵌套在Auth0Provider内部import { ConvexProviderWithAuth0 } from convex/react; Auth0Provider domain{AUTH0_DOMAIN} clientId{AUTH0_CLIENT_ID} ConvexProviderWithAuth0 client{convex} App / /ConvexProviderWithAuth0 /Auth0Provider文档明确要求使用官方示例中的 Provider 配置不要自行改写因为id_token的传递方式与刷新策略直接决定了 Convex 能否完成令牌校验。用 Convex auth state 控制 UI接入完成后是否渲染依赖 Convex 数据的 UI必须以 Convex 的认证状态为准而不是以 Auth0 自身的状态为准。这是因为 Auth0 登录成功只代表用户已在 Auth0 会话中而 Convex 还需要拿到有效的id_token并完成签名校验见下一节两者存在时间差与失败可能。技能的通用文档 SKILL.md 给出的建议是使用 Convex 提供的认证感知 UI 组件如Authenticated、Unauthenticated、AuthLoading或useConvexAuth()hook 来门控 UI确保在 Convex 确认会话之前受保护界面不渲染。后端函数保护ctx.auth.getUserIdentity()UI 层门控只是体验层面真正的安全边界在后端函数。后端保护的标准模式同样来自 SKILL.md 与源码佐证是绝不信任客户端传入的 userId而是在每个受保护函数内通过ctx.auth.getUserIdentity()校验身份// 错误示范信任客户端传入的 userId export const getMyProfile query({ args: { userId: v.id(users) }, handler: async (ctx, args) { return await ctx.db.get(args.userId); }, }); // 正确示范服务端验证身份 export const getMyProfile query({ args: {}, handler: async (ctx) { const identity await ctx.auth.getUserIdentity(); if (!identity) throw new Error(Not authenticated); return await ctx.db .query(users) .withIndex(by_tokenIdentifier, (q) q.eq(tokenIdentifier, identity.tokenIdentifier), ) .unique(); }, });关于getUserIdentity()的返回结构server/authentication.ts 中定义了UserIdentity接口其中唯一保证存在的字段是tokenIdentifier由 JWT 的subiss拼接而成全局稳定唯一与issuer其余 OIDC 标准字段如subject、name、email等是否出现取决于 Auth0 返回的声明内容此外还可通过类型断言读取 Auth0 JWT 中的自定义声明custom claims。在 Convex 后端Rust 侧中这一身份校验通过 isolate 运行时提供的 syscall 实现参见 crates/isolate/src/environment/udf/async_syscall.rs 中的相关 syscall 处理整个令牌解析与校验发生在服务端客户端无法伪造。是否创建应用级users表取决于应用是否需要把用户文档存入 Convex。文档明确并非每个应用都需要users表只有确实需要在 Convex 中保存用户文档时才添加且不要为 Auth0 这类第三方提供方机械照搬跨提供方 users 表 storeUser 流程。完整接入步骤清单综合原文档的 Workflow 与 Concrete Steps一份可执行的总步骤清单如下确认用户确实要 Auth0而非其他提供方确认应用框架检查 Auth0 是否已部分接入询问 local-only 还是 production-ready阅读官方 Convex Auth0 文档与对应框架的 Auth0 quickstart本地参考见 docs/auth/auth0.mdx询问用户是否接受 Auth0 CLI 最快路径若同意安装 CLI 并要求用户auth0 login若走 CLI用auth0 apps create创建 SPA 应用含 callback URL、logout URL、web origins机械性设置在 CLI 中完成若走 Dashboard完成前端 quickstart 并手动创建应用从 CLI 输出或 Dashboard 获取 Auth0 domain 与 client ID为应用框架安装 Auth0 SDK创建或更新convex/auth.config.ts填入 Auth0 domain 与 client ID设置前端与后端环境变量AUTH0_DOMAIN、AUTH0_CLIENT_ID、VITE_AUTH0_DOMAIN、VITE_AUTH0_CLIENT_ID等用Auth0Provider包裹应用将原有纯ConvexProvider接线替换为ConvexProviderWithAuth0修改后端配置后运行正常的 Convex dev 或 deploy 流程让后端同步配置用 Convex 认证状态门控受保护 UI验证登录后 Convex 报告用户已认证若为生产配置单独覆盖生产 Auth0 租户值、回调地址与生产环境变量。验证清单与失败处置原文档给出了严格的验证要求核心原则是Auth0 登录成功与Convex 能校验 Auth0 令牌是两件事必须同时成立。验证清单如下用户能完成 Auth0 登录流程Convex 认证状态的 UI 仅在 Convex auth state 就绪后渲染登录后受保护的 Convex query 能成功执行受保护后端函数中ctx.auth.getUserIdentity()返回非 null开发期间 Auth0 应用设置与本地真实 callback、logout URL 匹配若请求了生产配置生产 Auth0 配置同样被覆盖。失败处置原则重要文档多次强调如果 Auth0 登录或刷新链路出现文档无法明确解释的失败例如Unknown or invalid refresh token错误停止自行猜测修复明确告知用户该路径仍在调查中under investigation并把用户引导回官方文档手动完成。绝不能为了完成任务而谎称流程已验证。特别是 refresh-token 路径文档记录在验证中按照官方文档配置useRefreshTokens{true}与cacheLocationlocalstorage时遭遇了刷新令牌失败因此不应把该路径描述为已定论对应地ConvexProviderWithAuth0 的实现 默认依赖getAccessTokenSilently的静默刷新机制实际表现应结合 Auth0 应用设置与租户策略实测验证。生产环境配置若用户要求 production-ready 配置在宣布任务完成前必须确认生产 Auth0 租户的 domain、client ID 与回调地址是否已覆盖生产环境变量与 redirect 设置是否核验若开发与生产使用不同 Auth0 租户两者配置各自独立、互不混用。另外除非用户明确要求不要默认在仓库中写入笔记或交接文档如需产出 rollout 或 handoff 文档应先征得用户同意再创建。常见陷阱Gotchas速查不要跳过 Auth0 前端 quickstart——Convex 官方文档假设 Auth0 侧已就绪Auth0 CLI 最快但非完全验证路径仍需用户完成auth0 login认证 CLI用户同意安装 CLI 后机械性设置由自己完成不要又把用户推回 Dashboard登录成功但 Convex 仍报未认证时先检查convex/auth.config.ts与后端配置是否已同步重跑 dev/deploy不要混淆Auth0 登录可用与Convex 能校验 Auth0 令牌仓库已用 Auth0 时保留既有 redirect 与租户配置不要假设本地租户设置与生产一致生产 domain、client ID、回调地址单独核验本地开发时 Auth0 应用设置必须匹配真实端口遇到刷新令牌类错误不要无限试错退回官方文档并向用户说明现状。总结Auth0 与 Convex 的集成由三条主线构成Auth0 侧的 SPA 应用与回调配置CLI 或 Dashboard 路径、Convex 侧的令牌校验配置convex/auth.config.ts的domainapplicationID、前端接线Auth0Provider→ConvexProviderWithAuth0→ Convex 认证状态门控 UI 后端ctx.auth.getUserIdentity()保护。验证时必须同时确认 Auth0 登录与 Convex 会话识别都成功而对尚未验证的 refresh-token 路径应保持诚实、以官方文档为准。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐Redwood 集成 Auth0 认证从环境变量配置到 JWT 验证的完整实战指南Redwood 集成 Auth0 认证从环境变量配置到 JWT 验证的完整实战指南 Auth0 是 Redwood 官方提供的一等公民集成方案通过 red后端前端Web框架开发工具在 RedwoodJS 中集成 Auth0 认证从控制台配置到 JWT 验证的完整实战在 RedwoodJS 中集成 Auth0 认证从控制台配置到 JWT 验证的完整实战 本篇技术指南以 RedwoodJS 官方文档的 Auth0 认证章节为后端前端Web框架开发工具TDengine PI 数据接入连接配置与 Windows 集成认证完全指南TDengine PI 数据接入连接配置与 Windows 集成认证完全指南 PIOSIsoft PI System是电力、石化、制造等行业广泛使用的实时数据库时序数据库物联网大数据实时分析云原生上一篇突破百万面限制raytracing.github.io渲染引擎的内存优化终极指南下一篇LMCache Timeline-Semaphore Event IPC在无共享 /dev/shm 的隔离容器间实现零宿主机依赖的跨进程事件同步创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
