跳到主要内容

集成第三方OAuth 登录

  • 集成github、google
  • 使用better-auth

前置条件​

  • CLIENT_ID： 客户端ID （应用ID）
  • 当你的应用想用 GitHub / Google 登录时，第三方平台需要知道哪个应用在请求用户授权
    • 必须要配置CLIENT_ID才能在应用中实现登录
  • OAuth App 的客户端 ID，用于让你的应用通过 *GitHub/Google 登录（OAuth）
  • 获取用户授权。
    • CLIENT_ID 获取位置：
      • GitHub：Settings -> Developer settings -> OAuth Apps -> New OAuth App
      • Google：Google Cloud Console -> APIs & Services -> Credentials -> Create OAuth Client ID (Web application)

OAuth授权行为​

  • 第一次授权后，Google/Github 会记住这个客户端，之后再登录就直接换 token，跳过授权页面
  • prompt 是 OAuth 授权 URL 里的一个参数，用来控制授权页的行为
  • 可以通过修改prompt来调整授权行为
    • select_account：每次让用户选择账号
    • consent：每次要用户授权
    • none：不再弹授权页，直接用缓存（默认行为）
    • login：如果会话过期才弹登录

github授权登录​

  • 参考文档：https://better-auth.com/docs/authentication/github
  • 要使用 GitHub 登录，你需要客户端 ID 和客户端密钥
  • 重定向 URL 设置为 ：Better Auth 内部定义好的动态回调路由 （callback/github）
    • 本地开发：http://localhost:3000/api/auth/callback/github

注意：

  • 授权地址URL和回调重定向 URI 只能配置一个

google授权登录​

注意：

  • 和github不同，授权地址URL和回调重定向 URI 可以配置多个
  • 本地授权登录，需要代理，因为google授权登录之后，需要通过node服务来获取google token

better-auth​

  • 文档
  • BETTER_AUTH_SECRET
    • secret对应的属性配置
    • Better Auth 的应用级认证密钥
    • 签名和校验登录 Cookie
    • 加密 OAuth 状态等认证数据
    • 参与认证数据的加密、签名和哈希
    • 防止伪造登录会话
    • better Auth 官方说明，所有 Cookie 都会使用这个 secret 进行签名
  • 回调地址
    • 本地：http://localhost:3000/api/auth/callback/google
    • 生产：https://your-domain.com/api/auth/callback/google
  • BETTER_AUTH_URL
    • baseURL对应的路径、当前域名, 理解为认证服务的主机地址
    • 配置了baseURL之后，Better Auth 会生成 redirect_uri回调地址
  • Better Auth 校验 code 和 state，创建会话

数据库设计​

  • 账号表记录，如accounts
    • 记录oauth三方平台的账号信息
    • id、账号id、用户id、accessToken
  • 会话表记录，如session
    • 用户登录成功后，Better Auth 创建一条会话记录，并通过 HttpOnly Cookie 保存会话凭证
  • 短期校验表记录，如verifacations

账号表记录​

  • 用于第三方账号绑定记录
  • 用户绑定的一个 Google/GitHub/密码账号
  • accounts 账号表记录
  • 如一个用户绑定多个登录方式
text
provider_id：平台名称，例如 google、github、credential
account_id：第三方平台的稳定用户 ID，Google 中通常是 sub，不能使用邮箱代替
user_id：关联本地 users.id
password：账号密码登录时保存密码哈希，Google 登录为空
access_token、refresh_token、id_token：OAuth 令牌
scope：授权范围
access_token_expires_at、refresh_token_expires_at：令牌过期时间

会话表记录​

  • 用于服务端登录会话
  • sessions 会话表
  • 用户在一个浏览器或设备上的一次登录
  • 如多设备同时登录、退出所有设备、会话过期
text
id：会话 ID
token：会话凭证
user_id：所属用户
expires_at：过期时间
ip_address：登录 IP，可选
user_agent：浏览器或设备信息，可选
created_at、updated_at：会话时间

短期校验表记录​

邮箱注册登录，增加短期校验表，如果不需要邮箱注册登录，那么短期校验表可以不需要，注意短期校验表只是用于邮箱验证、找回密码

  • 用于短期一次性校验
  • verifications 校验表
  • 如用于保存临时的一次性校验记录、邮箱验证、找回密码、验证码等临时凭证
text
identifier：校验目标，例如邮箱或用户标识
value：验证码或一次性 Token
expires_at：过期时间
created_at、updated_at：时间字段