Butterbase 用户认证实战：邮箱 + OAuth 登录与 JWT 配置新手完整教程

Butterbase 用户认证实战邮箱 OAuth 登录与 JWT 配置新手完整教程【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-ossButterbase 是一款开源的 Backend-as-a-ServiceBaaS平台内建一套开箱即用的用户认证服务邮箱密码注册登录、魔法链接Magic Link无密登录、Google / GitHub / Apple 等 8 大 OAuth 第三方登录以及可灵活调整时效的 JWT 令牌体系。每个应用app_id都拥有相互隔离的用户账户与令牌端到端覆盖从注册、验证到登出的完整流程帮助开发者把写认证系统这件事从项目里彻底删掉。 本教程面向新手不需要你自己维护用户表、密码哈希或令牌刷新逻辑只需按步骤配置认证就能跑起来。1️⃣ Butterbase 认证功能总览一套 API 覆盖全部场景在动手之前先了解 Butterbase 认证文档中定义的完整能力矩阵能力说明典型接口 邮箱注册/登录自动发送 6 位验证码邮件强制密码复杂度/auth/{app_id}/signup、/login✨ 魔法链接登录无密码登录新用户首次验证时自动创建账户/auth/{app_id}/magic-link OAuth 社交登录内置 Google、GitHub、Discord、Facebook、LinkedIn、Microsoft、Apple、X 八大服务商/auth/{app_id}/oauth/{provider} JWT 令牌管理Access Token Refresh Token 双令牌自动轮换刷新/auth/{app_id}/refresh 邮箱验证 / 密码重置验证码 24 小时有效重置码 1 小时有效且重置后全端登出/verify-email、/reset-password️ 访问模式 RLS一键切换仅登录用户可访问并启用行级安全PATCH /config/access-mode、/secure 认证后钩子登录/注册成功后触发自定义函数发欢迎邮件、同步画像等post_auth_function 审计日志所有认证事件留痕可按用户、事件类型查询/v1/{app_id}/audit-logs下面这张图是一个使用 Butterbase 用户认证的应用CRM 模板的控制台概览可以看到认证只是应用整体能力中的一环其余数据库、存储、AI 网关均为平台托管 如果你赶时间也可以直接从官方模板起步——模板自带完整的认证配置克隆后稍加修改即可上线2️⃣ 五分钟上手邮箱注册与登录流程邮箱认证是整个体系的默认入口完整流程只有三步第 1 步 · 注册向POST /auth/{app_id}/signup提交邮箱、密码和昵称。密码需满足8 位以上 大小写 数字 特殊字符。注册成功后系统自动发出一封含6 位验证码的邮件此时用户尚未登录需要邮箱验证。第 2 步 · 验证邮箱用户输入验证码调用POST /auth/{app_id}/verify-email验证码 24 小时内有效。第 3 步 · 登录之后每次登录调用POST /auth/{app_id}/login成功即返回两枚令牌{ access_token: eyJhbGciOi..., refresh_token: ..., expires_in: 3600, token_type: Bearer, user: { id: uuid, email: userexample.com, email_verified: true } }Access Token访问令牌前端每次调用数据 API 时通过Authorization: Bearer头携带Refresh Token刷新令牌访问令牌过期后用于换取新令牌且旧令牌会立即失效令牌轮换防止被盗用反复重放。使用官方 TypeScript SDK 认证客户端时会话持久化、令牌自动刷新都帮你做完了await client.auth.signUp({ email, password, display_name }); await client.auth.signIn({ email, password }); // 自动保存会话 await client.auth.refreshSession(); // 到期前自动换新⏱️内置防滥用每个接口都带速率限制例如注册 5 次/15 分钟、登录 10 次/15 分钟、忘记密码 3 次/15 分钟防暴力破解和账号枚举详见 Auth API 参考。3️⃣ 三步配置 OAuth让 Google / GitHub 用户一键登录第 1 步 · 在服务商控制台创建应用以 Google 为例在 Google Cloud Console 创建 OAuth 客户端拿到client_id和client_secret并把回调地址填进已授权的重定向 URI。Butterbase 的回调地址格式固定为https://你的API域名/auth/{app_id}/oauth/google/callback第 2 步 · 向 Butterbase 注册服务商Butterbase内置 8 个主流服务商URL 与默认权限scopes全部自动填充你只需提供三样东西服务商默认 Scopes特殊说明googleopenid, email, profile—githubuser:email邮箱不公开时自动调用 /user/emails 补全discordidentify, email—facebookemail, public_profile—linkedinopenid, profile, email从 ID Token 提取信息microsoftopenid, email, profile, User.Read—applename, email需额外提供 teamId / keyId / privateKey且仅首次授权返回姓名xtweet.read, users.read使用 PKCE无邮箱自动生成占位邮箱通过 OAuth 配置 APIPOST /v1/{app_id}/auth/oauth-config一行请求即可注册实现代码位于 oauth-config 路由{ provider: google, client_id: YOUR_CLIENT_ID.apps.googleusercontent.com, client_secret: YOUR_CLIENT_SECRET, redirect_uris: [https://你的API域名/auth/app_xxx/oauth/google/callback] }更省事的方式接入 AI 编码工具后直接调用 MCP 的 manage_oauth 工具 说帮我配置 Google 登录即可完成它支持配置、查询、更新、删除四类操作且可安全重试。自定义服务商非内置则需额外提供authorization_url、token_url、userinfo_url三个地址PKCE 支持由 oauth_states 迁移脚本在底层实现。第 3 步 · 用户一键登录的四步旅程浏览器跳转到/auth/{app_id}/oauth/{provider}?redirect_to你的回调页用户在服务商页面完成授权服务商重定向回 Butterbase 的 callback 完成令牌交换用户被带回你的回调页令牌直接以查询参数形式附在 URL 上?access_token...refresh_token...。SDK 提供现成的回调处理函数自动读取令牌、拉取用户信息并清理 URL 避免令牌泄漏// 在你的 OAuth 回调页面里 const { data } await client.auth.handleOAuthCallback();安全细节GitHub 邮箱自动补全、Google/LinkedIn/Apple 通过 JWKS 解析 ID Token、Apple 的 POST 表单回调均已在 OAuth 流程路由中处理开发者零负担。4️⃣ JWT 配置两行参数掌控令牌生命周期访问令牌和刷新令牌的时效按应用独立配置存储在apps.jwt_config字段中见 JWT 配置迁移默认值为访问令牌 1 小时 / 刷新令牌 7 天参数可选值说明access_token_ttl15m / 30m / 1h / 2h / 1d访问令牌有效期refresh_token_ttl_days整数天刷新令牌有效期通过PATCH /v1/{app_id}/config/jwt接口或 MCP 工具update_jwt_config即可热更新例如把时效收紧到 15 分钟update_jwt_config({ access_token_ttl: 15m });为什么默认是 1 小时官方建议SSR 应用的 Cookie 会话可能比 JWT 活得久默认 1 小时可避免 Cookie 内嵌的令牌悄悄过期。若收紧到 15 分钟请确保客户端在过期前主动刷新。若你希望在自己的后端二次校验令牌真实性Butterbase 提供标准 JWKS 端点GET /auth/{app_id}/.well-known/jwks.json5 分钟缓存返回公钥供你本地验签无需每次回查服务端。5️⃣ 进阶两板斧访问模式与认证后钩子️ 一键上锁把应用变成登录后可见每个应用有一个access_mode模式行为public默认匿名请求可访问数据 API 与实时 WebSocketRLS 策略仍生效authenticated匿名请求一律 401仅登录用户的 JWT 和 API Key 放行更进一步POST /v1/{app_id}/secure是组合快捷键一次调用同时切到authenticated模式并为你列出的每张表自动启用 RLS 用户隔离策略 自动填充触发器例如{ tables: [ { table_name: posts, user_column: author_id } ] }配合public_read_column字段还能实现仅已发布内容公开可读这类精细规则详见 行级安全文档。 认证后钩子登录成功后自动做事在 认证配置 MCP 工具 或PATCH /v1/{app_id}/config/auth-hooks中指定一个已部署的函数名如post_auth_function: on-auth此后任何一次 OAuth 登录、邮箱登录或注册成功都会以发射后不管的方式调用它——绝不阻塞令牌下发。钩子收到的载荷包含eventoauth_login/signup/login、完整用户信息和isNewUser标记典型用法新用户注册时发送欢迎邮件把第三方登录的用户画像同步进自己的profiles表对magic_link_login等事件做风控埋点。钩子以butterbase_service角色运行可绕过 RLS注意用载荷里的用户信息而非ctx.user来识别身份。 附录相关资料与源码位置想深入某一块时按图索骥资料路径认证核心概念文档authentication.md认证 API 全量参考auth-api.mdTypeScript SDK 认证客户端auth-client.tsOAuth 配置路由实现oauth-config.tsOAuth MCP 工具manage-oauth.ts认证钩子 MCP 工具manage-auth-config.tsJWT 配置迁移脚本009_jwt_config.sqlPKCE / 服务商元数据迁移021_oauth_provider_enhancements.sql行级安全RLS文档row-level-security.md小结Butterbase 的用户认证把邮箱注册、魔法链接、OAuth 社交登录、JWT 令牌生命周期、访问控制与审计日志打包成一组以app_id隔离的接口新手按注册 → 配置 OAuth → 调整 JWT 时效 → 上锁 钩子四步走就能为应用交付一套生产级认证体系而不用自己碰任何密码学细节。【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考