convex-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<overview> Implement Convex authentication and authorization patterns with OIDC providers (Clerk, Auth0, WorkOS) or the built-in Convex Auth library. </overview> <reference> - **Auth overview**: https://docs.convex.dev/auth - **Convex Auth (beta)**: https://docs.convex.dev/auth/convex-auth - **Auth methods**: https://labs.convex.dev/auth - **Clerk Integration**: https://docs.convex.dev/auth/clerk - **WorkOS Integration**: https://docs.convex.dev/auth/authkit/ </reference> <context name="Auth Concepts"> - Convex uses OpenID Connect JWTs. - Integrations: Clerk, WorkOS AuthKit, Auth0; custom OIDC supported. - Convex Auth (Beta): A built-in library (labs.convex.dev) supporting Magic Links, OTPs, OAuth, and Passwords without external services. - Identity: Accessed via `ctx.auth.getUserIdentity()` in server functions. - Authorization: Enforced per public function; sensitive logic MUST use internal functions. </context> <rules>

<overview> 使用OIDC提供商（Clerk、Auth0、WorkOS）或内置的Convex Auth库实现Convex认证与授权模式。 </overview> <reference> - **认证概览**：https://docs.convex.dev/auth - **Convex Auth（测试版）**：https://docs.convex.dev/auth/convex-auth - **认证方法**：https://labs.convex.dev/auth - **Clerk集成**：https://docs.convex.dev/auth/clerk - **WorkOS集成**：https://docs.convex.dev/auth/authkit/ </reference> <context name="认证概念"> - Convex使用OpenID Connect JWT。 - 集成支持：Clerk、WorkOS AuthKit、Auth0；同时支持自定义OIDC。 - Convex Auth（测试版）：一款内置库（labs.convex.dev），无需外部服务即可支持魔法链接、一次性验证码（OTP）、OAuth及密码认证。 - 身份信息：可在服务器函数中通过`ctx.auth.getUserIdentity()`获取。 - 授权：针对每个公开函数执行；敏感逻辑必须使用内部函数。 </context> <rules>

Auth Operations

认证操作

In functions:

ctx.auth.getUserIdentity()

returns

tokenIdentifier

subject

issuer

plus provider claims.

Custom JWT auth MAY expose claims at
```
identity["properties.email"]
```
style paths.
User storage patterns:
- Client mutation to store user from JWT, or webhook from provider to upsert users.
- Index lookups SHOULD use
```
by_token
```
  /
```
byExternalId
```
  .
Webhooks: You MUST implement via HTTP actions and verify signatures with provider SDK; signing secrets MUST be stored in env vars.

在函数中：
```
ctx.auth.getUserIdentity()
```
会返回
```
tokenIdentifier
```
、
```
subject
```
、
```
issuer
```
以及提供商声明信息。
自定义JWT认证可通过
```
identity["properties.email"]
```
这类路径暴露声明信息。
用户存储模式：
- 通过客户端突变操作从JWT存储用户信息，或通过提供商的Webhook来更新/插入用户。
- 索引查询应使用
```
by_token
```
  /
```
byExternalId
```
  。
Webhook：必须通过HTTP操作实现，并使用提供商SDK验证签名；签名密钥必须存储在环境变量中。

Convex Auth (Beta) Specifics

Convex Auth（测试版）专属说明

Supported Methods:
1. Magic Links & OTPs: Email-based links or codes.
2. OAuth: GitHub, Google, Apple, etc.
3. Passwords: Supports reset flows and optional email verification.
Components: Does not provide UI components; You MUST build them in React using library hooks.
Next.js: SSR/Middleware support is experimental/beta.

支持的认证方式：
1. 魔法链接与一次性验证码（OTP）：基于邮箱的链接或验证码。
2. OAuth：支持GitHub、Google、Apple等平台。
3. 密码认证：支持重置流程及可选的邮箱验证。
组件：不提供UI组件；必须使用库中的hooks在React中自行构建。
Next.js：SSR/中间件支持处于实验性/测试阶段。

Server Function Patterns

服务器函数模式

You MUST read identity via
```
ctx.auth.getUserIdentity()
```
.
You MUST enforce row-level authorization in every public function.
You SHOULD NOT expose sensitive logic via public functions; prefer internal ones.

必须通过
```
ctx.auth.getUserIdentity()
```
读取身份信息。
必须在每个公开函数中执行行级授权校验。
不应通过公开函数暴露敏感逻辑；优先使用内部函数。

Service-to-service Access

服务间访问

If no user JWT is available, You SHOULD use a shared secret pattern.
You MUST store secrets in deployment env vars; MUST NOT hardcode.

当没有用户JWT可用时，应使用共享密钥模式。
必须将密钥存储在部署环境变量中；绝对不能硬编码。

Client Guidance

客户端指导

You MUST follow provider quickstarts; MUST NOT invent flows.
You SHOULD NOT rely on auth data in client-only code without server verification.

</rules>

必须遵循提供商的快速开始指南；切勿自行设计认证流程。
不应在仅客户端代码中依赖认证数据，必须经过服务器验证。

</rules>