OAuth2 账号系统 | Flarum OAuth Passport
English | 简体中文
一个独立的 Flarum 扩展，支持通过 Laravel Passport 或任何 OAuth2 兼容服务器进行 OAuth2 认证。无需依赖 fof/oauth - 完全可控的 OAuth 流程，自定义回调路由 /auth/passport。
功能
- 独立实现：不依赖
fof/oauth - 完全可控的 OAuth 流程
- 通用 OAuth2 支持：兼容 Laravel Passport、Keycloak、Auth0 或任何标准 OAuth2 服务器
- 灵活的用户数据映射：可配置 ID、显示名和邮箱字段名（支持 JSON
. 符号访问嵌套数据）
- 可自定义登录按钮：设置自定义标题、图标（FontAwesome）、背景色和文字颜色
- 账号关联：通过 OAuth 服务器提供的 ID 自动关联账号
- 资料同步：可选在每次登录时更新显示名和邮箱
- 无密码选项：隐藏默认用户名/密码字段，实现纯 OAuth 认证
- 弹窗配置：支持全屏弹窗或自定义宽高
- 应用内浏览器支持：内置微信等应用内置浏览器的回调处理机制
- 迁移支持：无缝从
blt950/oauth-generic 和 fof/passport 迁移
安装
使用 扩展程序管理器 或通过 composer 手动安装：
composer require import-ai/flarum-oauth-passport:"*"
更新
composer update import-ai/flarum-oauth-passport:"*"
php flarum migrate
php flarum cache:clear
配置
- 进入 管理后台 > 扩展 > OAuth Passport
- 将 重定向 URL 复制到 OAuth 服务器的允许重定向 URL 列表中
- 配置 OAuth 接口和凭证（见下文）
OAuth 服务器设置
| 设置项 | 说明 |
|---|
| 客户端 ID | OAuth 应用的客户端 ID |
| 客户端密钥 | OAuth 应用的客户端密钥 |
| 作用域 | 逗号分隔的 OAuth 作用域（默认：read） |
| 授权接口 | OAuth 授权 URL（如：https://auth.example.com/oauth/authorize） |
| 令牌接口 | OAuth 令牌 URL（如：https://auth.example.com/oauth/token） |
| 用户信息接口 | 用户信息 URL（如：https://auth.example.com/api/user） |
用户数据映射
配置 OAuth 服务器用户信息响应中的字段名：
| 设置项 | 默认值 | 点符号支持 |
|---|
| 用户 ID 字段 | id | 支持（如：data.user.id） |
| 显示名字段 | name | 支持（如：data.name） |
| 邮箱地址字段 | email | 支持（如：data.email） |
用户注册选项
| 设置项 | 说明 |
|---|
| 强制使用用户 ID 作为用户名 | 使用 OAuth 用户 ID 作为 Flarum 用户名，不允许用户选择 |
| 强制使用显示名 | 使用 OAuth 显示名，不允许用户选择 |
| 强制使用邮箱地址 | 使用 OAuth 邮箱并标记为已验证 |
| 登录时更新显示名 | 每次登录时从 OAuth 服务器同步显示名 |
| 登录时更新邮箱地址 | 每次登录时从 OAuth 服务器同步邮箱 |
登录按钮自定义
| 设置项 | 默认值 | 说明 |
|---|
| 按钮标题 | “使用 Passport 登录” | 登录按钮上显示的文本 |
| 按钮图标 | fas fa-passport | FontAwesome 图标类名 |
| 按钮背景颜色 | #3B82F6 | 十六进制颜色代码 |
| 按钮文字颜色 | #ffffff | 十六进制颜色代码 |
弹窗设置
| 设置项 | 默认值 | 说明 |
|---|
| 全屏弹窗 | false | 使用全屏弹窗进行 OAuth（忽略宽高设置） |
| 弹窗宽度 | 580 | OAuth 弹窗宽度（像素） |
| 弹窗高度 | 400 | OAuth 弹窗高度（像素） |
高级选项
- 替换登录/注册按钮：隐藏默认用户名/密码字段，仅显示 OAuth 按钮
OAuth 流程
- 用户点击"使用 Passport 登录"按钮
- 扩展携带 state 参数重定向到 OAuth 服务器（CSRF 防护）
- 用户在 OAuth 服务器上完成认证
- OAuth 服务器重定向回
/auth/passport?code=xxx&state=xxx
- 扩展验证 state 并将授权码交换为访问令牌
- 扩展获取用户信息并创建/登录 Flarum 用户
- 可选：派发
OAuthLoginSuccessful 事件供自定义处理
从其他扩展迁移
本扩展内置迁移支持：
blt950/oauth-genericfof/passport
只需安装本扩展，现有的 OAuth 关联账号将继续正常工作。
事件
扩展在 OAuth 登录成功后派发 FoF\Extend\Events\OAuthLoginSuccessful 事件，允许其他扩展执行自定义操作：
use FoF\Extend\Events\OAuthLoginSuccessful;
$events->listen(OAuthLoginSuccessful::class, function (OAuthLoginSuccessful $event) {
$token = $event->token; // League\OAuth2\Client 的 AccessToken
$user = $event->user; // ResourceOwnerInterface
$provider = $event->provider; // 'passport'
$providerId = $event->providerId;
$actor = $event->actor; // 当前用户（未登录时为 null）
});
应用内浏览器支持
针对微信等会拦截弹窗的环境，扩展包含中间件来检测应用内浏览器，并提供 OAuth 认证完成的回退机制。
系统要求
- Flarum 1.2.0 或更高版本
- PHP 7.4 或更高版本
- OAuth2 兼容的身份验证服务器
链接