convex-setup-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Authentication Setup

Convex 认证配置指南

Implement secure authentication in Convex with user management and access control.

在Convex中实现具备用户管理和访问控制的安全认证机制。

When to Use

适用场景

Setting up authentication for the first time
Implementing user management (users table, identity mapping)
Creating authentication helper functions
Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom JWT)

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

First Step: Choose the Auth Provider

第一步：选择认证提供商

Convex supports multiple authentication approaches. Do not assume a provider.

Before writing setup code:

Ask the user which auth solution they want, unless the repository already makes it obvious
If the repo already uses a provider, continue with that provider unless the user wants to switch
If the user has not chosen a provider and the repo does not make it obvious, ask before proceeding

Common options:

Convex Auth - good default when the user wants auth handled directly in Convex
Clerk - use when the app already uses Clerk or the user wants Clerk's hosted auth features
WorkOS AuthKit - use when the app already uses WorkOS or the user wants AuthKit specifically
Auth0 - use when the app already uses Auth0
Custom JWT provider - use when integrating an existing auth system not covered above

Look for signals in the repo before asking:

Dependencies such as
```
@clerk/*
```
,
```
@workos-inc/*
```
,
```
@auth0/*
```
, or Convex Auth packages
Existing files such as
```
convex/auth.config.ts
```
, auth middleware, provider wrappers, or login components
Environment variables that clearly point at a provider

Convex支持多种认证方式，请勿默认指定某一提供商。

编写配置代码前：

询问用户希望使用哪种认证方案，除非代码仓库已明确使用某一提供商
若仓库已使用某提供商，继续沿用该方案，除非用户要求切换
若用户未选择且仓库无明确线索，需先询问用户再继续

常见选项：

Convex Auth - 当用户希望直接在Convex中处理认证时，这是不错的默认选择
Clerk - 适用于应用已使用Clerk，或用户需要Clerk托管式认证功能的场景
WorkOS AuthKit - 适用于应用已使用WorkOS，或用户明确需要AuthKit的场景
Auth0 - 适用于应用已使用Auth0的场景
自定义JWT提供商 - 适用于集成上述未覆盖的现有认证系统

询问前可先从仓库中寻找线索：

依赖包如
```
@clerk/*
```
、
```
@workos-inc/*
```
、
```
@auth0/*
```
或Convex Auth相关包
现有文件如
```
convex/auth.config.ts
```
、认证中间件、提供商包装器或登录组件
明确指向某提供商的环境变量

After Choosing a Provider

选定提供商后

Read the provider's official guide and the matching local reference file:

Convex Auth: official docs, then
```
references/convex-auth.md
```
Clerk: official docs, then
```
references/clerk.md
```
WorkOS AuthKit: official docs, then
```
references/workos-authkit.md
```
Auth0: official docs, then
```
references/auth0.md
```

The local reference files contain the concrete workflow, expected files and env vars, gotchas, and validation checks.

Use those sources for:

package installation
client provider wiring
environment variables
```
convex/auth.config.ts
```
setup
login and logout UI patterns
framework-specific setup for React, Vite, or Next.js

For shared auth behavior, use the official Convex docs as the source of truth:

Auth in Functions for
```
ctx.auth.getUserIdentity()
```
Storing Users in the Convex Database for optional app-level user storage
Authentication for general auth and authorization guidance
Convex Auth Authorization when the provider is Convex Auth

Do not invent a provider-agnostic user sync pattern from memory. For third-party providers, only add app-level user storage if the app actually needs user documents in Convex. For Convex Auth, do not add a parallel

users

table plus

storeUser

flow. Follow the Convex Auth docs and built-in auth tables instead.

Do not invent provider-specific setup from memory when the docs are available. Do not assume provider initialization commands finish the entire integration. Verify generated files and complete the post-init wiring steps the provider reference calls out.

阅读该提供商的官方指南及对应的本地参考文件：

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作为提供商时的指南

请勿凭记忆设计与提供商无关的用户同步模式。对于第三方提供商，仅当应用确实需要在Convex中存储用户文档时，才添加应用级用户存储。对于Convex Auth，请勿额外创建并行的

users

表及

storeUser

流程，请遵循Convex Auth文档及内置的认证表进行操作。

当文档可查时，请勿凭记忆设计提供商专属的配置流程。请勿假设提供商的初始化命令能完成全部集成工作，请验证生成的文件并完成提供商参考文档中提到的初始化后配置步骤。

Workflow

工作流程

Determine the provider, either by asking the user or inferring from the repo
Ask whether the user wants local-only setup or production-ready setup now
Read the matching provider reference file
Follow the official provider docs for current setup details
Follow the official Convex docs for shared backend auth behavior, user storage, and authorization patterns
Only add app-level user storage if the docs and app requirements call for it
Add authorization checks for ownership, roles, or team access only where the app needs them
Verify login state, protected queries, environment variables, and production configuration if requested

If the flow blocks on interactive provider or deployment setup, ask the user explicitly for the exact human step needed, then continue after they complete it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow after setup is done. If the environment has browser automation tools, you can use them. If it does not, give the user a short manual validation checklist instead.

通过询问用户或从仓库推断确定认证提供商
询问用户当前需要仅本地环境配置还是生产就绪的配置
阅读对应的提供商参考文件
遵循提供商官方文档完成当前配置细节
遵循Convex官方文档完成通用后端认证行为、用户存储及授权模式配置
仅当文档及应用需求明确要求时，才添加应用级用户存储
仅在应用需要的位置添加所有权、角色或团队访问权限的授权检查
若用户要求，验证登录状态、受保护的查询、环境变量及生产配置

若流程因需要交互式的提供商或部署配置而停滞，请明确告知用户需要完成的具体人工步骤，待用户完成后再继续。对于面向UI的认证流程，配置完成后可主动提出验证实际注册或登录流程。若环境具备浏览器自动化工具，可使用该工具进行验证；若没有，则为用户提供简短的手动验证清单。

Reference Files

参考文件

Provider References

提供商参考

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

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

Checklist

检查清单

Chosen the correct auth provider before writing setup code
Read the relevant provider reference file
Asked whether the user wants local-only setup or production-ready setup
Used the official provider docs for provider-specific wiring
Used the official Convex docs for shared auth behavior and authorization patterns
Only added app-level user storage if the app actually needs it
Did not invent a cross-provider
```
users
```
table or
```
storeUser
```
flow for Convex Auth
Added authentication checks in protected backend functions
Added authorization checks where the app actually needs them
Clear error messages ("Not authenticated", "Unauthorized")
Client auth provider configured for the chosen provider
If requested, production auth setup is covered too

编写配置代码前已选定正确的认证提供商
已阅读相关的提供商参考文件
已询问用户需要仅本地环境配置还是生产就绪的配置
已使用提供商官方文档完成提供商专属的配置
已使用Convex官方文档完成通用认证行为及授权模式配置
仅当应用确实需要时才添加了应用级用户存储
未为Convex Auth额外创建交叉提供商的
```
users
```
表或
```
storeUser
```
流程
已在受保护的后端函数中添加认证检查
已在应用需要的位置添加授权检查
已设置清晰的错误提示（如“未认证”、“无权限”）
已针对选定的提供商配置客户端认证提供商
若用户要求，已完成生产环境的认证配置