# 更好的身份验证集成指南 ## 概述 Better Auth 是 TypeScript 的综合身份验证框架，提供类型安全身份验证，支持多个提供商、2FA、SSO、组织等。该技能涵盖了 NestJS 后端与 Drizzle ORM 和 PostgreSQL 的完整集成模式，以及 Next.js App Router 前端集成。 ## 何时使用 * 使用 NestJS 后端设置更好的身份验证 * 将 Next.js App Router 前端与 Better Auth 集成 * 使用 PostgreSQL 配置 Drizzle ORM 模式进行身份验证 * 实现社交登录（GitHub、Google、Facebook、微软等） * 使用 TOTP 添加多重身份验证 (MFA/2FA) * 实现passkey（WebAuthn）无密码身份验证 * 管理可信设备以简化身份验证 * 使用备份代码进行 2FA 帐户恢复 * 添加身份验证插件（2FA、组织、SSO、Magic Link、Passkey） * 具有安全会话管理功能的电子邮件/密码身份验证 * 创建受保护的路由和身份验证中间件 * 实施基于角色的访问控制（RBAC） * 与组织一起构建多租户应用程序 ## 快速入门 ### 安装 # 后端 (NestJS) npm 安装 better-auth @auth/drizzle-adapter npm 安装 drizzle-orm pg npm install -D 毛毛雨套件 # 前端 (Next.js) npm 安装更好的身份验证 ### 基本设置 1.配置Better Auth实例（后端） 2. 使用 Better Auth 表设置 Drizzle 架构 3.在NestJS中创建auth模块 4. 配置 Next.js 身份验证客户端 5. 为受保护的路由设置中间件有关详细设置说明，请参阅参考资料/。 ## 架构 ### 后端 (NestJS) 源代码/ ├── 授权/ │ ├── auth.module.ts # Auth模块配置 │ ├── auth.controller.ts # Auth HTTP端点 │ ├── auth.service.ts # 业务逻辑 │ ├── auth.guard.ts # 路由保护 │ └── schema.ts # Drizzle auth schema ├── 数据库/ │ ├── database.module.ts # 数据库模块 │ └── database.service.ts # 小雨连接 └── main.ts ### 前端 (Next.js) 应用程序/ ├──（授权）/ │ ├── 登录/ │ │ └── page.tsx # 登录页面 │ └── 报名/ │ └── page.tsx # 注册页面 ├──（仪表板）/ │ ├── 仪表板/ │ │ └── page.tsx # 受保护的页面 │ └──layout.tsx # 带授权检查 ├── API/ │ └── 授权/ │ └── [...auth]/route.ts # Auth API 路由 ├──layout.tsx # 根布局 └── middleware.ts # 认证中间件库/ ├── auth.ts # 更好的身份验证客户端 └── utils.ts ## 说明 ### 第 1 阶段：数据库设置 1. **安装依赖项** npm install drizzle-orm pg @auth/drizzle-adapter better-auth npm install -D 毛毛雨套件 2. **配置毛毛雨** * 创建 `drizzle.config.ts` * 设置数据库连接 * 使用 Better Auth 表定义模式 3. **生成并运行迁移** npx drizzle-kit 生成 npx drizzle-kit 迁移 ### 第 2 阶段：后端设置 (NestJS) 1. **创建数据库模块** * 设置 Drizzle 连接 * 提供数据库服务 2. **配置更好的身份验证** * 使用 Drizzle 适配器创建身份验证实例 * 配置提供商（GitHub、Google 等） * 设置会话管理 3. **创建身份验证模块** * 具有端点的身份验证控制器 * 带有业务逻辑的Auth服务 * Auth Guard 保护 ### 第 3 阶段：前端设置 (Next.js) 1. **配置身份验证客户端** * 设置更好的身份验证客户端 * 配置服务器动作 2. **创建身份验证页面** * 登录页面 * 注册页面 * 错误处理 3. **添加中间件** * 保护路线 * 处理重定向 ### 第 4 阶段：高级功能 1. **社会提供商** * 配置 OAuth 应用程序 * 添加提供者回调 2. **插件** * 双因素身份验证 (2FA) * 组织机构 * 单点登录 * 魔法链接 * 密钥 ## 示例 ### 示例 1：完成 NestJS 身份验证设置 **输入：** 开发人员需要在带有 PostgreSQL 的新 NestJS 项目中设置 Better Auth。 **流程：** // 1. 创建auth实例导出 const auth = betterAuth({ 数据库：drizzleAdapter(db, { 提供者：“pg”，架构：{ ...架构 } }), 社交提供者：{ github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, } } }); // 2.创建auth控制器 @Controller('授权') 导出类 AuthController { @全部('*') 异步handleAuth（@Req（）req：请求，@Res（）res：响应）{ 返回 auth.handler(req); } } **输出：** `/auth/*` 处的功能齐全的身份验证端点，具有 GitHub OAuth 支持。 ### 示例 2：用于路由保护的 Next.js 中间件 **输入：** 保护 Next.js App Router 中的仪表板路由。 **流程：** // 中间件.ts 从'@/lib/auth'导入{auth}；导出默认身份验证((req) => { if (!req.auth && req.nextUrl.pathname.startsWith('/dashboard')) { const newUrl = new URL('/登录', req.nextUrl.origin); 返回 Response.redirect(newUrl); } }); 导出常量配置= { 匹配器：['/dashboard/:path*', '/api/protected/:path*'] }; **输出：** 未经身份验证的用户在访问“/dashboard/*”时会被重定向到“/sign-in”。 ### 示例 3：带有会话的服务器组件 **输入：** 在 Next.js 服务器组件中显示用户数据。 **流程：** // 应用程序/仪表板/page.tsx 从'@/lib/auth'导入{auth}；从“下一步/导航”导入{重定向}；导出默认异步函数 DashboardPage() { const 会话 = 等待 auth(); 如果（！会话）{ 重定向（'/登录'）； } 返回（

欢迎，{session.user.name}

电子邮件：{session.user.email}

）； } **输出：** 仅呈现经过身份验证的用户的用户信息，重定向其他人登录。 ### 示例 4：添加双因素身份验证 **输入：** 启用 2FA 以增强帐户安全性。 **流程：** // 启用 2FA 插件导出 const auth = betterAuth({ 插件：[ 双因子({ 发行人：'MyApp'， otp选项：{ 数字：6，期限：30 } }) ] }); // 客户端启用2FA const { 数据，错误 } = 等待 authClient.twoFactor.enable({ 密码：'用户密码' }); **输出：** 用户可以启用基于 TOTP 的 2FA 并使用身份验证器应用程序进行验证。 ### 示例 5：使用可信设备进行 TOTP 验证 **输入：** 用户已启用 2FA 并希望登录，将设备标记为可信。 **流程：** // 服务器端：配置 2FA 和 OTP 发送导出 const auth = betterAuth({ 插件：[ 双因子({ 发行人：'MyApp'， otp选项：{ 异步 sendOTP({ 用户, otp }, ctx) { // 通过电子邮件、短信或其他方法发送 OTP 等待发送电子邮件({ 至：用户.电子邮件，主题：'您的验证码'，正文：`代码：${otp}` }); } } }) ] }); // 客户端：验证 TOTP 并信任设备 const verify2FA = async（代码：字符串）=> { const { 数据，错误 } = 等待 authClient.twoFactor.verifyTotp({ 代码， trustDevice: true // 设备可信 30 天 }); 如果（数据）{ // 重定向到仪表板 router.push('/仪表板'); } }; **输出：** 用户已通过身份验证，设备受信任 30 天（下次登录时不会出现 2FA 提示）。 ### 示例 6：密钥身份验证设置 **输入：** 启用密钥 (WebAuthn) 身份验证以进行无密码登录。 **流程：** // 服务器端：配置密钥插件从'@better-auth/passkey'导入{passkey}；导出 const auth = betterAuth({ 插件：[ 密钥（{ rpID: 'example.com', // 依赖方 ID（您的域） rpName: '我的应用', // 显示名称高级：{ webAuthnChallengeCookie：“我的应用程序密码” } }) ] }); // 客户端：注册密钥 const registerPasskey = async () => { const { 数据，错误 } = 等待 authClient.passkey.register({ 名称：“我的设备” }); 如果（数据）{ console.log('密码注册成功'); } }; // 客户端：使用密钥登录 const signInWithPasskey = async () => { 等待 authClient.signIn.passkey({ autoFill: true, // 启用条件 UI 获取选项：{ onSuccess() { router.push('/仪表板'); } } }); }; **输出：** 用户可以使用密钥（生物识别、PIN 或安全密钥）进行注册和身份验证。 ### 示例 7：密钥条件 UI（自动填充） **输入：** 在登录表单中实现密钥自动填充以实现无缝身份验证。 **流程：** // 具有条件 UI 支持的组件 '使用客户端'；从'react'导入{useEffect}；从 '@/lib/auth/client' 导入 { authClient }；导出默认函数 SignInPage() { 使用效果（（）=> { // 检查条件中介支持 if (!PublicKeyCredential.isConditionalMediationAvailable || !PublicKeyCredential.isConditionalMediationAvailable()) { 返回； } // 启用密钥自动填充 void authClient.signIn.passkey({ autoFill: true }); }, []); 返回（ <表格> 电子邮件： <输入类型=“电子邮件” 姓名=“电子邮件” autoComplete="用户名 webauthn" /> 密码： <输入类型=“密码” 名称=“密码” autoComplete="当前密码 webauthn" /> ）； } **输出：** 当用户关注输入字段时，浏览器会自动建议密钥。 ### 示例 8：2FA 恢复的备份代码 **输入：** 如果身份验证器应用程序丢失，用户需要备份代码来恢复帐户。 **流程：** // 启用 2FA - 自动生成备份代码 const enable2FA = async（密码：字符串）=> { const { 数据，错误 } = 等待 authClient.twoFactor.enable({ 密码 }); 如果（数据）{ // 重要提示：立即向用户显示备份代码 console.log('备份代码（安全保存）：'); data.backupCodes.forEach((代码：字符串) => { 控制台.log(代码); }); // 将 TOTP URI 显示为 QR 码 const qrCodeUrl = data.totpURI; 显示QRCode(qrCodeUrl); } }; // 使用备份代码恢复 const recoveryWithBackupCode = async（代码：字符串）=> { const { 数据，错误 } = 等待 authClient.twoFactor.verifyBackupCode({ 代码 }); 如果（数据）{ // 允许用户禁用 2FA 或设置新的身份验证器 router.push('/settings/2fa'); } }; **输出：** 用户收到用于帐户恢复的一次性备份代码。 ## 常见模式 ### 受保护的路由模式 // NestJS 守卫 @Controller('仪表板') @UseGuards(AuthGuard) 导出类 DashboardController { @Get() getDashboard(@Request() 请求) { 返回请求用户； } } // Next.js 服务器组件从'@/lib/auth'导入{auth}；从“下一步/导航”导入{重定向}；导出默认异步函数 Dashboard() { const 会话 = 等待 auth(); 如果（！会话）{ 重定向（'/登录'）； } return

欢迎{session.user.name}

; } ### 会话管理模式 // 获取API路由中的session const 会话 = 等待 auth.api.getSession({ 标题：等待标题（） }); // 在服务器组件中获取会话 const 会话 = 等待 auth(); // 在客户端组件中获取会话 '使用客户端'；从'@/lib/auth/client'导入{useSession}； const { 数据：会话 } = useSession(); ## 最佳实践 1. **环境变量**：始终将环境变量用于敏感数据（机密、数据库 URL、OAuth 凭据） 2. **秘密生成**：使用强大、独特的秘密来实现更好的身份验证。使用 `openssl rand -base64 32` 生成 3. **需要 HTTPS** ：OAuth 回调在生产中需要 HTTPS。使用“ngrok”或类似的工具进行本地测试 4. **会话安全**：根据您的安全要求配置适当的会话过期时间 5. **数据库索引** : 在经常查询的字段（电子邮件、用户 ID）上添加索引以提高性能 6. **错误处理**：在不泄露敏感信息的情况下对身份验证失败实施正确的错误处理 7. **速率限制** ：为身份验证端点添加速率限制以防止暴力攻击 8. **CSRF 保护**：更好的身份验证包括 CSRF 保护。始终使用提供的方法进行状态更改 9. **类型安全**：利用 Better Auth 中的 TypeScript 类型在前端和后端实现完整的类型安全 10. **测试**：彻底测试身份验证流程，包括成功案例、错误案例和边缘条件 ## 限制和警告 ### 安全说明 * **从不提交机密** ：将 `.env` 添加到 `.gitignore` 并且从不提交 OAuth 机密或数据库凭据 * **验证重定向 URL** ：始终验证 OAuth 重定向 URL 以防止开放重定向 * **哈希密码**：Better Auth 自动处理密码哈希。永远不要实现自己的 * **会话存储** ：对于生产，使用 Redis 或其他可扩展的会话存储 * **仅 HTTPS** ：在生产中始终使用 HTTPS 进行身份验证 * **OAuth 机密**：确保 OAuth 客户端机密的安全。定期轮换它们 * **电子邮件验证** ：始终为基于密码的身份验证实施电子邮件验证 ### 已知限制 * 更好的身份验证需要 Node.js 18+ 才能支持 Next.js App Router * 一些 OAuth 提供商需要特定的重定向 URL 格式 * 密钥需要 HTTPS 和兼容的浏览器 * 组织功能需要额外的数据库表 ## 版本要求 ### 后端依赖 { “依赖项”：{ “更好的身份验证”：“^1.2.0”， "@auth/drizzle-adapter": "^1.0.0", "毛毛雨-orm": "^0.35.0", "pg": "^8.12.0", "@nestjs/common": "^10.0.0", "@nestjs/core": "^10.0.0", "@nestjs/config": "^3.0.0" }, “开发依赖项”：{ "毛毛雨套件": "^0.24.0", "@types/pg": "^8.11.0" } } ### 前端依赖项 { “依赖项”：{ “更好的身份验证”：“^1.2.0”， "下一个": "^15.0.0", “反应”：“^19.0.0”， “反应-dom”：“^19.0.0” } } ### 数据库 * 推荐 PostgreSQL 14+ * 对于本地开发：Docker PostgreSQL 或 Postgres.app ## 故障排除 ### 1\. “找不到会话”错误 **问题**：会话数据未正确保存或检索。 **解决方案**： * 验证数据库连接是否正常 * 检查会话表是否存在并且有数据 * 确保“BETTER_AUTH_SECRET”设置一致 * 验证 cookie 域设置与您的应用程序域匹配 ### 2\. OAuth 回调失败并显示“状态无效” **问题**：回调期间 OAuth 状态不匹配。 **解决方案**： * 清除cookies并重试 * 确保环境中正确设置“BETTER_AUTH_URL” * 检查 OAuth 应用程序中的重定向 URI 是否完全匹配 * 验证没有反向代理正在修改回调 ### 3\. auth() 的 TypeScript 类型错误 **问题**：类型推断无法正常工作。 **解决方案**： * 确保安装了 TypeScript 5+ * 使用`npx better-auth typegen`生成类型 * 在 IDE 中重新启动 TypeScript 服务器 * 检查前端和后端的“better-auth”版本是否匹配 ### 4\.迁移失败并显示“表已存在” **问题**：Drizzle 迁移冲突。 **解决方案**： * 删除现有表并重新运行迁移 * 或者使用 `drizzle-kit Push` 进行开发 * 对于生产，编写手动迁移来处理现有表 ### 5\.从前端到后端的 CORS 错误 **问题**：前端无法与后端身份验证端点通信。 **解决方案**： * 在NestJS后端配置CORS * 将前端源添加到允许的源中 * 确保包含凭据：`credentials: 'include'` ### 6\.社交提供商返回“redirect_uri_mismatch” **问题**：OAuth 应用程序配置不匹配。 **解决方案**： * 使用准确的回调 URL 更新 OAuth 应用程序 * 包括和生产 URL * 对于 ngrok/本地测试，每次 URL 更改时更新 OAuth 应用程序 ## 资源 ### 文档 * [更好的身份验证文档]() * [Drizzle ORM 文档]() * [NestJS 文档]() * [Next.js 应用路由器文档]() ### 参考实现 * 请参阅 `references/nestjs-setup.md` 以获取完整的 NestJS 设置 * 请参阅 `references/nextjs-setup.md` 以获取完整的 Next.js 设置 * 插件配置请参见 `references/plugins.md` * 有关示例代码文件，请参阅“assets/” ### 环境变量有关所有必需的环境变量，请参阅“Assets/env.example”。 ## 环境变量 # 数据库 DATABASE_URL=postgresql://用户:密码@localhost:5432/dbname # 更好的身份验证 BETTER_AUTH_SECRET=您的秘密密钥最少 32 个字符 BETTER_AUTH_URL=http://localhost:3000 # OAuth 提供者 AUTH_GITHUB_CLIENT_ID=您的 github 客户端 ID AUTH_GITHUB_CLIENT_SECRET=您的 github 客户端秘密 AUTH_GOOGLE_CLIENT_ID=您的 google 客户端 ID AUTH_GOOGLE_CLIENT_SECRET=您的 google 客户端秘密 # 电子邮件（用于魔法链接和验证） SMTP_HOST=smtp.example.com SMTP_端口=587 SMTP_USER=您的 smtp 用户 SMTP_PASSWORD=您的 smtp 密码 SMTP_FROM=noreply@example.com # 会话（可选，对于 Redis） REDIS_URL=redis://localhost:6379

更好的身份验证

包含技能