convex-setup-auth

Convex 身份验证设置

在 Convex 中实现安全的身份验证，并管理用户和访问权限。

适用场景

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

不适用场景

• 为非 Convex 后端设置身份验证
• 纯 OAuth/OIDC 文档，没有 Convex 实现
• 调试与身份验证代码无关、只是恰好在其附近出现的问题
• 身份验证提供商已完全配置完毕，用户只需要一行修复代码

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

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 设置
• 登录和登出 UI 模式
• React、Vite 或 Next.js 的框架专属设置

对于通用身份验证行为，请以 Convex 官方文档为准：

• ctx.auth.getUserIdentity() 请参阅 函数中的身份验证
• 如需在应用层存储用户，请参阅 在 Convex 数据库中存储用户
• 一般身份验证和授权指南，请参阅 身份验证
• 使用 Convex Auth 时，请参阅 Convex Auth 授权

优先参考官方文档，而不是凭记忆操作，因为不同版本的提供商 CLI 和 Convex Auth 内部实现可能会发生变化。凭记忆编造设置步骤可能会导致使用过时模式。对于第三方提供商，只有在应用确实需要在 Convex 中存储用户文档时，才添加应用层用户存储。并非每个应用都需要 users 表。对于 Convex Auth，请遵循 Convex Auth 文档并使用其内置身份验证表，而不是额外添加一张 users 表和 storeUser 流程，因为 Convex Auth 已在内部管理用户记录。运行提供商初始化命令后，请检查生成的文件，并完成提供商参考文档列出的初始化后配置步骤。初始化命令很少能完成整个集成。

核心模式：保护后端函数

最常见的身份验证任务是在 Convex 函数中检查身份。

// Bad: trusting a client-provided userId
export const getMyProfile = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

// Good: verifying identity server-side
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();
  },
});

工作流

1. 确定提供商，可询问用户或根据代码仓库推断
2. 询问用户现在需要仅本地设置，还是可用于生产环境的设置
3. 阅读对应的提供商参考文件
4. 遵循提供商官方文档，了解当前的设置详情
5. 遵循 Convex 官方文档，了解通用后端身份验证行为、用户存储和授权模式
6. 只有在文档和应用需求要求时，才添加应用层用户存储
7. 仅在应用需要时，为所有权、角色或团队访问添加授权检查
8. 如果用户有此要求，则验证登录状态、受保护的查询、环境变量和生产环境配置

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

参考文件

提供商参考

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

检查清单

• 编写设置代码前，已选择正确的身份验证提供商
• 已阅读相关提供商参考文件
• 已询问用户需要仅限本地的设置，还是可用于生产环境的设置
• 提供商特定的接线配置已参考提供商官方文档
• 通用身份验证行为和授权模式已参考 Convex 官方文档
• 仅在应用确实需要时才添加应用级用户存储
• 未为 Convex Auth 臆造跨提供商的 users 表或 storeUser 流程
• 已在受保护的后端函数中添加身份验证检查
• 已在应用确实需要的地方添加授权检查
• 错误消息清晰（“未通过身份验证”、“未获授权”）
• 已为所选提供商配置客户端身份验证提供商
• 如果用户有要求，也涵盖了生产环境身份验证设置