Convex 认证设置用于在 Convex 中实现带用户管理和访问控制的安全认证。
适用场景
- 首次为项目设置认证
- 实现用户管理（users 表、identity 映射）
- 创建认证辅助函数
- 配置认证提供商（Convex Auth、Clerk、WorkOS AuthKit、Auth0、自定义 JWT）
不适用场景
- 非 Convex 后端的认证
- 纯 OAuth/OIDC 文档、不含 Convex 实现
- 与认证无关、只是恰好在认证代码附近出现的 bug 调试
- 认证提供商已完整配置，只需一行修复
第一步：选择认证提供商 Convex 支持多种认证方式，不要自行假设提供商。在编写设置代码前：
- 询问用户想用哪种认证方案，除非仓库已经明确表明
- 如果仓库已使用某提供商，除非用户想切换，否则沿用该提供商
- 如果用户未选择且仓库未表明，先询问再继续
常见选项：
- Convex Auth：用户希望在 Convex 内直接处理认证时的良好默认选择
- Clerk：应用已使用 Clerk，或用户需要 Clerk 的托管认证功能时使用
- WorkOS AuthKit：应用已使用 WorkOS，或用户特别需要 AuthKit 时使用
- Auth0：应用已使用 Auth0 时使用
- 自定义 JWT 提供商：集成上述未覆盖的现有认证系统时使用
询问前可先在仓库中寻找信号：
- 依赖，如 @clerk/、@workos-inc/、@auth0/* 或 Convex Auth 相关包
- 已有文件，如 convex/auth.config.ts、认证中间件、提供商包装器或登录组件
- 明确指向某提供商的环境变量
选定提供商之后 阅读该提供商的官方指南以及对应的本地参考文件：
- Convex Auth：官方文档，然后 references/convex-auth.md
- Clerk：官方文档，然后 references/clerk.md
- WorkOS AuthKit：官方文档，然后 references/workos-authkit.md
- Auth0：官方文档，然后 references/auth0.md
本地参考文件包含具体工作流、预期文件与环境变量、注意事项和验证检查。可使用这些来源处理：
- 包安装
- 客户端提供商接线
- 环境变量
- convex/auth.config.ts 配置
- 登录与登出 UI 模式
- React、Vite 或 Next.js 的框架特定设置
共享认证行为以 Convex 官方文档为准：
- Auth in Functions：ctx.auth.getUserIdentity()
- Storing Users in the Convex Database：可选的应�用层用户存储
- Authentication：通用认证与授权指南
- Convex Auth Authorization：提供商为 Convex Auth 时
优先使用官方文档而非凭记忆复述的步骤，因为提供商 CLI 与 Convex Auth 内部实现会随版本变化，凭记忆编造设置有使用过时模式的风险。对于第三方提供商，仅当应用确实需要在 Convex 中存在用户文档时才添加应用层用户存储；并非每个应用都需要 users 表。对于 Convex Auth，应遵循 Convex Auth 文档和内置认证表，而不是额外添加并行的 users 表加 storeUser 流程，因为 Convex Auth 已在内部管理用户记录。运行提供商初始化命令后，要验证生成的文件，并完成提供商参考文件指出的初始化后接线步骤；初始化命令很少能完成整个集成。
核心模式：保护后端函数 最常见的认证任务是在 Convex 函数中检查身份。
错误示例：信任客户端传入的 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();
}, });
工作流
- 确定提供商：询问用户，或从仓库推断
- 询问用户是要仅本地设置还是现在就做生产就绪设置
- 阅读对应提供商参考文件
- 按官方提供商文档处理当前设置细节
- 按官方 Convex 文档处理共享后端认证行为、用户存储与授权模式
- 仅当文档和应用需求要求时，才添加应用层用户存储
- 仅在应用需要处，为所有权、角色或团队访问添加授权检查
- 如被要求，验证登录状态、受保护查询、环境变量和生产配置
如果流程卡在交互式提供商或部署设置上，明确告诉用户需要完成的确切人工步骤，待其完成后再继续。对于面向 UI 的认证流程，设置完成后可提议验证真实的注册或登录流程；若环境具备浏览器自动化工具可使用，如没有则给用户一份简短的手工验证清单。
参考文件
- references/convex-auth.md
- references/clerk.md
- references/workos-authkit.md
- references/auth0.md
检查清单
- 在编写设置代码前已选对认证提供商
- 已阅读相关提供商参考文件
- 已询问用户要仅本地设置还是生产就绪设置
- 提供商特定接线使用官方提供商文档
- 共享认证行为与授权模式使用官方 Convex 文档
- 仅在应用确实需要时才添加应用层用户存储
- 没有为 Convex Auth 编造跨提供商的 users 表或 storeUser 流程
- 在受保护后端函数中添加了认证检查
- 在应用确实需要处添加了授权检查
- 错误信息清晰（"Not authenticated"、"Unauthorized"）
- 已为所选提供商配置客户端认证提供商
- 如被要求，生产认证设置也已覆盖
限制
- 不适用于非 Convex 后端
- 不适用于不含 Convex 实现的纯 OAuth/OIDC 文档
- 不用于调试与认证无关的 bug
- 提供商已完整配置、只需一行修复时不在适用范围内
- 具体安装命令、环境变量名称、价格与平台支持未在资料中提供，需以官方提供商文档与 Convex 官方文档为准