better-auth

Better Auth 集成指南

概述

Better Auth 是一个类型安全的 TypeScript 身份验证框架，支持多个提供商、2FA、SSO、组织和通行密钥。本技能介绍适用于 NestJS 后端（搭配 Drizzle ORM + PostgreSQL）和 Next.js App Router 前端的集成模式。

适用场景

• 在 NestJS 后端中配置 Better Auth
• 集成 Next.js App Router 前端
• 配置搭配 PostgreSQL 的 Drizzle ORM 架构
• 实现社交登录（GitHub、Google、Facebook、Microsoft）
• 添加 MFA/2FA、TOTP、通行密钥无密码身份验证或魔法链接
• 管理可信设备和用于账户恢复的备用代码
• 使用组织或 SSO 构建多租户应用
• 使用会话管理创建受保护的路由

快速开始

安装

# Backend (NestJS)
npm install better-auth @auth/drizzle-adapter drizzle-orm pg
npm install -D drizzle-kit

# Frontend (Next.js)
npm install better-auth

四阶段配置

1. 数据库：安装 Drizzle、配置架构、运行迁移
2. 后端：创建 Better Auth 实例并配置 NestJS 模块
3. 前端：配置身份验证客户端、创建页面、添加中间件
4. 插件：按需添加 2FA、通行密钥、组织功能

完整的后端配置请参见 references/nestjs-setup.md，插件配置请参见 references/plugins.md。

说明

第一阶段：数据库配置

1. 安装依赖

   npm install drizzle-orm pg @auth/drizzle-adapter better-auth
   npm install -D drizzle-kit
   

2. 创建 Drizzle 配置（drizzle.config.ts）

   import { defineConfig } from 'drizzle-kit';
   export default defineConfig({
     schema: './src/auth/schema.ts',
     out: './drizzle',
     dialect: 'postgresql',
     dbCredentials: { url: process.env.DATABASE_URL! },
   });
   

3. 生成并运行迁移

   npx drizzle-kit generate
   npx drizzle-kit migrate
   

   检查点：验证表已创建：运行 psql $DATABASE_URL -c "\dt" 后，应显示 user、account、session、verification_token 表。

第二阶段：后端配置（NestJS）

1. 创建数据库模块——设置 Drizzle 连接服务

2. 配置 Better Auth 实例

   // src/auth/auth.instance.ts
   import { betterAuth } from 'better-auth';
   import { drizzleAdapter } from '@auth/drizzle-adapter';
   import * as schema from './schema';
   
   export const auth = betterAuth({
     database: drizzleAdapter(schema, { provider: 'postgresql' }),
     emailAndPassword: { enabled: true },
     socialProviders: {
       github: {
         clientId: process.env.AUTH_GITHUB_CLIENT_ID!,
         clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET!,
       }
     }
   });
   

3. 创建身份验证控制器

   @Controller('auth')
   export class AuthController {
     @All('*')
     async handleAuth(@Req() req: Request, @Res() res: Response) {
       return auth.handler(req);
     }
   }
   

   检查点：测试端点 GET /auth/get-session，未通过身份验证时应返回 { session: null }（无错误）。

第三阶段：前端配置（Next.js）

1. 配置身份验证客户端（lib/auth.ts）

   import { createAuthClient } from 'better-auth/client';
   export const authClient = createAuthClient({
     baseURL: process.env.NEXT_PUBLIC_APP_URL!
   });
   

2. 添加中间件（middleware.ts）

   import { auth } from '@/lib/auth';
   export default auth((req) => {
     if (!req.auth && req.nextUrl.pathname.startsWith('/dashboard')) {
       return Response.redirect(new URL('/sign-in', req.nextUrl.origin));
     }
   });
   export const config = { matcher: ['/dashboard/:path*'] };
   

3. 创建登录页面，添加表单或社交登录按钮

   检查点：退出登录时访问 /dashboard，应重定向到 /sign-in。

第四阶段：高级功能

添加 references/plugins.md 中的插件：

• 2FA：twoFactor({ issuer: 'AppName', otpOptions: { sendOTP } })

• 通行密钥：passkey({ rpID: 'domain.com', rpName: 'App' })

• 组织：organization({ avatar: { enabled: true } })

• 魔法链接：magicLink({ sendMagicLink })

• SSO：sso({ saml: { enabled: true } })

  检查点：添加插件后，重新运行迁移并验证新表是否存在。

示例

示例 1：带会话的服务端组件

输入：在 Next.js 服务端组件中显示用户数据。

// app/dashboard/page.tsx
import { auth } from '@/lib/auth';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const session = await auth();

  if (!session) {
    redirect('/sign-in');
  }

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <p>Email: {session.user.email}</p>
    </div>
  );
}

输出：为已通过身份验证的用户渲染用户信息；将未通过身份验证的用户重定向到登录页面。

示例 2：使用可信设备进行 2FA TOTP 验证

输入：用户已启用 2FA，并希望登录，同时将设备标记为可信设备。

// Server: Configure 2FA with OTP sending
export const auth = betterAuth({
  plugins: [
    twoFactor({
      issuer: 'MyApp',
      otpOptions: {
        async sendOTP({ user, otp }, ctx) {
          await sendEmail({
            to: user.email,
            subject: 'Your verification code',
            body: `Code: ${otp}`
          });
        }
      }
    })
  ]
});

// Client: Verify TOTP and trust device
const verify2FA = async (code: string) => {
  const { data } = await authClient.twoFactor.verifyTotp({
    code,
    trustDevice: true  // Device trusted for 30 days
  });

  if (data) {
    router.push('/dashboard');
  }
};

输出：用户通过身份验证；设备在 30 天内被视为可信设备，无需提示进行 2FA。

示例 3：通行密钥注册和登录

输入：启用通行密钥（WebAuthn）身份验证，实现无密码登录。

// Server
import { passkey } from '@better-auth/passkey';
export const auth = betterAuth({
  plugins: [
    passkey({
      rpID: 'example.com',
      rpName: 'My App',
    })
  ]
});

// Client: Register passkey
const registerPasskey = async () => {
  const { data } = await authClient.passkey.register({
    name: 'My Device'
  });
};

// Client: Sign in with autofill
const signInWithPasskey = async () => {
  await authClient.signIn.passkey({
    autoFill: true,  // Browser suggests passkey
  });
};

输出：用户可以通过生物识别、PIN 或安全密钥注册并进行身份验证。

更多示例（备用代码、组织、魔法链接、条件 UI），请参见 references/plugins.md 和 references/passkey.md。

最佳实践

1. 环境变量：将所有机密信息存储在 .env 中，并将其添加到 .gitignore
2. 生成机密信息：使用 openssl rand -base64 32 生成 BETTER_AUTH_SECRET
3. 需要 HTTPS：OAuth 回调需要 HTTPS（本地测试时使用 ngrok）
4. 会话过期时间：根据安全要求进行配置（默认 7 天）
5. 数据库索引：为 email、userId 添加索引以提升性能
6. 错误处理：返回通用错误，不要暴露敏感细节
7. 速率限制：为身份验证端点添加速率限制，以防止暴力攻击
8. 类型安全：使用 npx better-auth typegen 实现完整的 TypeScript 覆盖

限制与警告

安全说明

• 切勿提交机密信息：将 .env 添加到 .gitignore；切勿提交 OAuth 机密信息或数据库凭据
• 验证重定向 URL：始终验证 OAuth 重定向 URL，以防止开放重定向
• 哈希密码：Better Auth 会自动处理密码哈希；切勿自行实现哈希
• 会话存储：在生产环境中使用 Redis 或其他可扩展的会话存储
• 仅使用 HTTPS：在生产环境中始终使用 HTTPS 进行身份验证
• 电子邮件验证：始终为基于密码的身份验证实现电子邮件验证

已知限制

• Better Auth 需要 Node.js 18+ 才能支持 Next.js App Router
• 某些 OAuth 提供商需要特定格式的重定向 URL
• Passkey 需要 HTTPS 和兼容的浏览器
• 组织功能需要额外的数据库表

资源

文档

• Better Auth - 官方文档
• Drizzle ORM - 数据库 ORM
• NestJS - 后端框架
• Next.js - 前端框架

参考实现

• references/nestjs-setup.md - 完整的 NestJS 后端设置
• references/nextjs-setup.md - 完整的 Next.js 前端设置
• references/plugins.md - 插件配置（2FA、Passkey、组织、SSO、魔法链接）
• references/mfa-2fa.md - 详细的 MFA/2FA 指南
• references/passkey.md - 详细的 Passkey 实现
• references/schema.md - Drizzle 模式参考
• references/social-providers.md - 社交提供商配置