auth-setup

Convex 身份验证设置

在 Convex 中实现安全身份验证，包括用户管理和访问控制。

适用场景

• 首次设置身份验证
• 实现用户管理（用户表、身份映射）
• 创建身份验证辅助函数
• 设置身份验证提供方（Convex Auth、Clerk、WorkOS AuthKit、Auth0、自定义 JWT）

第一步：选择身份验证提供方

Convex 支持多种身份验证方式。不要默认选择某个提供方。

编写设置代码前：

1. 询问用户希望使用哪种身份验证方案，除非仓库中已有明显线索
2. 如果仓库已在使用某个提供方，则继续使用该提供方，除非用户想要切换
3. 如果用户尚未选择提供方，且仓库中没有明显线索，则先询问再继续

常见选项：

• 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
• 设置登录和退出登录界面模式
• 配置 React、Vite 或 Next.js 的相关设置

然后阅读 references/common-patterns.md，了解适用于所有提供方的 Convex 端模式：

• 将 ctx.auth.getUserIdentity() 映射到 users 表
• getCurrentUser 和 getCurrentUserOrNull
• requireAdmin 等授权辅助函数
• 所有权检查和团队成员资格检查
• 公开、私有和混合查询模式

文档可用时，不要凭记忆编造特定提供方的设置。 不要假设提供方的初始化命令会完成整个集成。请检查生成的文件，并完成提供方参考文档中列出的初始化后接线步骤。

工作流

1. 通过询问用户或根据代码仓库推断提供商
2. 询问用户现在需要仅限本地的设置，还是可用于生产环境的设置
3. 阅读对应的提供商参考文件
4. 遵循提供商官方文档，了解当前的设置详情
5. 应用 references/common-patterns.md 中的 Convex 通用模式
6. 仅当应用需要 users 表时，才接入 storeUser 或等效的身份同步机制
7. 根据需要添加所有权、管理员访问权限或团队访问权限的授权检查
8. 如果用户提出要求，验证登录状态、受保护的查询、环境变量和生产配置

如果流程因交互式提供商设置或部署设置而受阻，请明确询问用户需要完成的具体人工操作，然后在用户完成后继续。 对于面向 UI 的身份验证流程，设置完成后，主动提出验证实际注册或登录流程。 如果环境中有浏览器自动化工具，可以使用这些工具。 如果没有，请向用户提供简短的手动验证清单。

参考文件

提供商参考

• references/convex-auth.md
• references/clerk.md
• references/workos-authkit.md
• references/auth0.md

通用模式

• references/common-patterns.md

检查清单

• 编写设置代码前已选择正确的身份验证提供商
• 已阅读相关的提供商参考文件
• 已询问用户需要仅限本地的设置，还是可用于生产环境的设置
• 已使用提供商官方文档接入特定提供商
• users 表包含 tokenIdentifier 索引
• getCurrentUser 辅助函数
• 首次登录时调用 storeUser mutation
• 所有受保护函数中均有身份验证检查
• 对资源访问进行授权检查
• 提供清晰的错误消息（“未通过身份验证”“未授权”）
• 已为所选提供商配置客户端身份验证提供商
• 如果用户提出要求，也已涵盖生产环境的身份验证设置