[RFC] 089 - 支持 OAuth2.0 6749 Refresh Token & Database Session

[cy948]

背景

文中使用的名词均在 RFC 6749 有详细定义。

OAuth 授权支持

PR#1143 的合并标志 LobeChat 正式接入 OAuth，为用户资源提供保护。在当前的实现中，LobeChat 用户中使用 Github 登陆时，各个服务承担的角色：

OAuth 角色	具体实体	说明
资源所有者 (Resource Owner)	使用 LobeChat 的用户	用户通过 GitHub 账号登录 LobeChat，是资源的实际拥有者（如 GitHub 账号信息）。
客户端 (Client)	LobeChat 应用	LobeChat 是请求访问用户 GitHub 数据的第三方应用，NextAuth 作为客户端库处理 OAuth 流程。
授权服务器 (Authorization Server)	GitHub 的 OAuth 服务	GitHub 负责用户身份认证、授权同意，并颁发访问令牌（如 https://github.com/login/oauth）。
资源服务器 (Resource Server)	GitHub 的 API（如用户信息接口）	GitHub 提供用户数据的 API（如 https://api.github.com/user），验证令牌后返回用户信息。

     +--------+                               +---------------+
     |        |--(A)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(B)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(C)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(D)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(E)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(F)--- Protected Resource ---|               |
     +--------+                               +---------------+
                     Figure 1: Abstract Protocol Flow

Figure 1: Abstract Protocol Flow

当前 OAuth 接入的优缺点

从上述过程中可以发现，授权服务器 (Authorization Server)完成授权后，后续的会话、用户管理都由 LobeChat 进行管理。这种实现：

• 优点👍：用户授权完成后不受授权服务器控制，Lobe 可以实现更灵活的访问控制。
• 缺点👎：管理员无法通过授权服务对用户进行管理，如禁用用户等。

但因当前的 OAuth 实现，实际上只停留在 Social Connection（社交连接）的层面。 Social Connection 通常指通过用户的社交媒体账号（如 Google、Facebook、GitHub 等）实现第三方应用登录或身份绑定的机制。其核心目标是简化用户注册/登录流程，提升用户体验，同时借助已有社交平台的信任体系。本质上还是一种登录、身份绑定机制，在社区同学的使用过程中，出现了这些实际问题：

• 用户身份控制能力弱
  • 现状：第三方SSO作为唯一身份提供方（IdP），无法直接管理用户（如修改身份信息、禁用账号、强制重置密码）。
    • [Bug] 使用Logto身份验证，退出登录后再点"登录/注册"，会自动登录刚退出的账号 #6411
    • [Bug]OIDC颁发的token失效后，页面能否失去登录态 #6094
    • [Request] Set restriction / access control for SSO users / conversation access  #4564
    • [Request] Enhanced User Management, Synchronization, and Security Features #1403
    • [Request] Auth and management role #499
  • 问题：用户生命周期管理复杂（如跨平台数据同步、删除用户）。
• 会话与令牌管理简单
  • 现状：当前的 NextAuth 接入为 JWT ，缺乏对用户会话管理的灵活性。
    • [Bug] auth0 Logout not working correctly & Autologin #4701
    • [Bug] 没办法真正意义上的退出用户登录状态 #3646
  • 问题：当前 Session 并未与 IdP 同步，可能导致 IdP 禁用用户后，用户仍然能在一定周期内继续使用。
• 用户数据存储分散
  • 现状：除了支持 Webhooks 的服务外，其他均不能及时更新用户信息，如头像、展示名称等。
    • [Request] 从 OIDC 处获取用户头像 #5898
  • 问题：用户数据分散在 GitHub 和 LobeChat 本地数据库，难以统一管理。

归根到底，这些问题产生的原因是LobeChat没有定期向Authorization Server询问Client的可用状态。在后续的补充实现 PR#3774 中，我们通过对资源服务器 (Resource Server) Webhook 支持减缓了“用户数据存储分散”的问题，但剩下问题的解决需要以下功能的支持，也就是本 RFC 提议的 Refresh Token & Database Session 支持。

Refresh Token 支持

Refresh Token 流程

在 PR#6209 的实现中，以用户使用 Auth0 登录，并向 Auth0 请求 Refresh Token 的过程：

实体/角色	对应你的场景	RFC 6749 定义
客户端 (Client)	LobeChat 应用后端代用户主动刷新Token	持有用户授权、代表用户访问资源的应用（需在 Auth0 注册为 OAuth 客户端）。
授权服务器 (Authorization Server)	Auth0	颁发令牌（Access Token 和 Refresh Token）的服务器（如 Auth0 的令牌端点）。
资源服务器 (Resource Server)	可能由 LobeChat 或第三方提供	存储用户资源（如用户数据 API），需验证 Access Token 合法性。

  +--------+                                           +---------------+
  |        |--(A)------- Authorization Grant --------->|               |
  |        |                                           |               |
  |        |<-(B)----------- Access Token -------------|               |
  |        |               & Refresh Token             |               |
  |        |                                           |               |
  |        |                            +----------+   |               |
  |        |--(C)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(D)- Protected Resource --| Resource |   | Authorization |
  | Client |                            |  Server  |   |     Server    |
  |        |--(E)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(F)- Invalid Token Error -|          |   |               |
  |        |                            +----------+   |               |
  |        |                                           |               |
  |        |--(G)----------- Refresh Token ----------->|               |
  |        |                                           |               |
  |        |<-(H)----------- Access Token -------------|               |
  +--------+           & Optional Refresh Token        +---------------+

               Figure 2: Refreshing an Expired Access Token

Refresh Token 支持意义及挑战

1. 核心价值

• 安全令牌轮换：Access Token 短期有效（如 1 小时），即使泄露，攻击窗口有限。
• 后台服务访问：支持异步任务（如定时同步用户数据到 LobeChat，无需 WebHook 推送）。

2. 在 LobeChat 中的实现挑战

• 安全存储：Refresh Token 必须加密存储，避免泄露。
• 动态更新：需处理 Refresh Token 的自动续期和失效（如用户主动注销时立即使旧 Token 失效）。
• 权限控制：新颁发的 Access Token 权限范围（scope）不可超过原始授权。

实现

方案

针对以上问题，提出一种能满足Lobe及Auth服务对用户进行管理的方案：

• Lobe 主动向 Auth 读取用户授权状态（需开启 Token Rotation）：在Lobe中，在Auth服务授权的访问令牌（access_token）进行刷新，以获取当前用户在 Auth 服务的授权状态：正常、禁用：
  • 正常：进行 token 刷新，保持用户的登录状态。
  • 禁用：无法进行 token 时，强制用户重新登录。
• Auth 服务主动向 Lobe 推送用户可用状态（需开启 Webhook, database session ）：Auth服务会在“禁用”用户时，通过webhook向lobe发送事件，Lobe可在收到事件后，清除目标用户的会话，强制用户重新登录。

依据 AuthJS 文档建议的实现，在用户请求 session 时，前往 Auth 服务刷新令牌，使 Lobe 用户的登录状态受到 Auth 服务约束，实现以下功能：

• 当 Auth 服务 suspend 用户时， Lobe 会主动注销 session 并登出

进度

• ✨feat: Support database session & token refresh for sso providers #6209
• Refresh Token 支持（1期，包含 Auth0, Logto, Casdoor）
• Database Session 实现
• Webhook 拓展支持
• 后端用户 Profile 刷新
• 兼容性测试

SSO	Refresh Token	Webhook	Database Session	Refresh Profile	Test
Logto	✅	🚧	✅	🚧	🚧
Auth0	✅	🚫	✅	🚧	🚧
Casdoor	🚫	🚧	✅	🚧	🚧

工程踩坑记录

• 已知问题：因为 next-auth 会多次并发调用 auth，导致该实现需要并发刷新 token （并发调用[G]->[H]）。而 Casdoor 是RFC6749中推荐的 refresh token 只能使用1次的实现，因而暂时无法接入。待 AuthJS 的全局锁实现后可以接入。

[cy948]

前置工作

添加兼容 Edge 环境的ORM实例

因为需要在中间件中使用 Database，需要一个能在 Edge 环境下工作的 serverDB ：

• 从 src/database/server/core/db.ts 中抽离与 Edge 环境兼容的 serverDB 到文件 src/database/server/core/dbForEdge.ts。
• 原理是利用模组加载机制，使运行 Edge 部分代码时不会 import 非 Edge Runtime 的模块。

拓展定义 NextAuth Session 类型

• 为了刷新 Session，需要为默认的内置类型拓展定义
• src/types/next-auth.d.ts 处 import { JWT } from 'next-auth/jwt'; 通过显式 import JWT类型，防止 tsc 执行 type check 时检查报错。

在鉴权路由中添加对 NextAuth 错误的抛出及拦截

• 在 src/utils/server/auth.ts, src/server/context.ts 中识别并拦截 NextAuth 的错误信息。

• 添加兼容 Edge 环境的ORM实例

• 拓展定义 NextAuth Session 类型

• 在鉴权路由中添加对 NextAuth 错误的抛出及拦截

[cy948]

Token Refresh 实现

在 SSO Provider 中添加 Token Refresh 的支持

• scope: 授权域中添加 offline_access；cy948@1bc0df7
• profile: 用户profile处理中添加对 issuer 端点信息的返回；cy948@1bc0df7
• refreshToken: 为 SSO Provider 添加刷新 token 的方法实现; 1bc0df7

在 AuthConfig Callbacks 中添加对信息的处理

src/libs/next-auth/auth.config.ts

• 传递 SSO Provider 返回的 issuer 信息到 Session
• 传递 Token Refresh 过程中的信息到 Session

适时调用 SSO Provider 提供的 Token Refresh 方法

在 src/libs/next-auth/auth.config.ts 中，当用户通过环境变量启用 Token Refresh 后，有以下情况会调用 Token Refresh 方法：

• 用户没有启用 Database Session：
• 用户启用 Database Session：