身份验证

在 LaunchSaaS 中配置 Better Auth，支持社交登录（Google、GitHub）、魔术链接、角色权限控制和安全会话管理。

LaunchSaaS 使用 Better Auth 进行身份验证，提供灵活且安全的系统，支持多种身份验证方法、会话管理和基于角色的访问控制。

当前边界是：

apps/launchsaas/src/lib/auth/auth.ts 负责 Better Auth 的 server 构建
apps/launchsaas/src/lib/auth/auth-client.ts 负责 Better Auth 的 client 构建
apps/launchsaas/src/components/layout/better-auth-ui-provider.tsx 负责把 auth client 和 router、i18n、客户端可见的 auth UI 配置接起来
apps/launchsaas/src/components/{auth,settings} 存放应用消费的 Better Auth UI source-vendor 组件

设置

1. 生成 Better Auth 密钥

BETTER_AUTH_SECRET 是用于加密和生成哈希的随机字符串。使用 VictoryHub 生成一个或运行：

openssl rand -base64 32

将其添加到你的 .env 文件：

BETTER_AUTH_SECRET="your-generated-secret-key"

2. 配置 Email/Password（可选）

Email/password 身份验证通过 src/configuration/features.ts 中的 features.auth.emailPasswordEnabled 默认启用。登录无需邮件 Provider — 邮件 Provider 仅用于发送验证邮件和密码重置邮件。

如需禁用（例如纯 OAuth 应用），将标志设为 false：

// apps/your-app/src/configuration/features.ts
auth: {
  emailPasswordEnabled: false,
  ...
},

如需在注册时要求邮箱验证，将 requireEmailVerification 设为 true（同时需要配置邮件 Provider）：

auth: {
  emailPasswordEnabled: true,
  requireEmailVerification: true,  // 默认为 false
  ...
},

未配置邮件 Provider 时登录依然正常。验证邮件和密码重置邮件会在没有 Provider 时静默跳过 — 通过 /launchsaas add-capability email 配置 Provider 后即可激活。

3. 配置 Magic Link（可选）

Magic link 默认禁用。启用步骤：

确保已配置邮件 Provider（发送链接需要）
打开 src/configuration/features.ts，将 magicLinkEnabled 设置为 true：

auth: {
  ...
  magicLinkEnabled: true,
},

启用后，Better Auth 会向用户邮箱发送一次性登录链接，登录 UI 会自动显示 magic link 选项。

Magic link 依赖邮件 Provider。如果 capabilities.email 为 null，magic link 插件不会被注册，请求会静默失败。

4. 配置 GitHub OAuth（可选）

前往 GitHub 开发者设置
点击"OAuth Apps"→"New OAuth App"
填写注册表单：
- 应用名称：你的应用名称
- 主页 URL：http://localhost:3000（或你的生产环境 URL）
- 授权回调 URL：http://localhost:3000/api/auth/callback/github
点击"Register application"
生成客户端密钥
添加到你的 .env 文件：

NEXT_PUBLIC_GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"

为开发和生产环境创建单独的 OAuth 应用。它们需要不同的回调 URL。

4. 配置 Google OAuth（可选）

前往 Google Cloud Console
创建新项目或选择现有项目
前往"凭据"→"创建凭据"→"OAuth 客户端 ID"
如果提示，配置 OAuth 同意屏幕
创建 OAuth 客户端 ID：
- 应用类型：Web 应用程序
- 已授权的 JavaScript 来源：http://localhost:3000
- 已授权的重定向 URI：http://localhost:3000/api/auth/callback/google
添加到你的 .env 文件：

NEXT_PUBLIC_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

5. 配置 CAPTCHA（可选）

设置 CAPTCHA_SECRET_KEY 后，CAPTCHA 会自动激活，无需修改代码。

请参阅 CAPTCHA 配置指南了解支持的 Provider 和详细设置步骤。

LaunchSaaS 身份验证包括：

Email/Password - 注册、登录和密码重置（默认启用；在 src/configuration/features.ts 中将 emailPasswordEnabled: false 以禁用；将 requireEmailVerification: true 以在注册时要求邮箱验证）
Magic Link - 无密码身份验证（默认禁用；在 src/configuration/features.ts 中将 magicLinkEnabled: true 以启用 — 需要邮件 Provider）
社交登录 - Google 和 GitHub OAuth（添加 client ID 环境变量后启用）
CAPTCHA - 支持 Cloudflare Turnstile、Google reCAPTCHA、hCaptcha 和 CaptchaFox（添加 CAPTCHA_SECRET_KEY 后启用；详见 CAPTCHA 指南）
会话管理 - 服务器端会话处理
基于角色的访问 - 用户和管理员角色
App 持有 Auth Wiring - server、client 和 auth UI 都由你的 app 维护