第三方登录账号

一、插件简介

第三方登录（oauth）面向社区站点，支持 微信、QQ 开放平台网站应用登录。登录弹窗展示第三方图标，用户授权后回调本站，自动登录已绑定账号或按策略注册新账号。

适合降低注册门槛、提升登录转化。

• 前台入口：登录/注册弹窗第三方图标（auth_login_extra 插槽）
• 后台入口：应用中心 → 第三方登录 → 配置（无独立后台菜单）
• 主要路径（伪静态后缀下同）：
• GET /oauth/wechat、GET /oauth/qq — 跳转授权
• GET /oauth/{provider}/callback — 授权回调
• POST /oauth/unbind — 解绑（账号设置）

二、核心能力

三、依赖与安装

建议环境：

• 已安装并启用 社区（community） 插件（登录会话、会员中心）
• 微信开放平台已创建 网站应用 并审核通过
• QQ 互联已创建应用并审核通过
• 回调域名与开放平台配置一致（须 HTTPS 生产环境）

安装步骤：

1. 应用中心安装并启用 第三方登录
2. 在微信/QQ 开放平台配置授权回调域与回调 URI
3. 在应用中心填写 AppID/AppSecret（或 QQ 的 APP ID/Key）
4. 分别开启「启用微信登录」「启用 QQ 登录」
5. 决定「未绑定账号时自动注册」策略
6. 前台登录弹窗测试授权流程

数据表：

• {prefix}oauth_account — 第三方账号与本站用户绑定关系

四、应用中心基础配置

路径：应用中心 → 第三方登录 → 配置

enabledProviders 逻辑： 总开关开启 + 对应平台开关开启 + AppID/Secret 均已填写，方显示入口。

五、开放平台配置（重点）

5.1 微信开放平台

1. 创建「网站应用」，获取 AppID、AppSecret
2. 授权回调域填写本站域名（不含路径）
3. 回调 URI 须为：https://你的域名/oauth/wechat/callback
4. 网站应用需通过审核

5.2 QQ 互联

1. 创建网站应用，获取 APP ID、APP Key
2. 回调地址：https://你的域名/oauth/qq/callback
3. 应用需通过审核

5.3 绑定模式

已登录用户访问 /oauth/{provider}?intent=bind 可将第三方账号绑定到当前用户（Session oauth_intent）。

六、前台用户流程

第三方登录

1. 用户打开登录弹窗，点击微信或 QQ 图标
2. 跳转第三方授权页，用户同意授权
3. 回调本站 /oauth/{provider}/callback
4. 系统校验 state，获取 openid/unionid 等信息
5. 若已绑定 → 直接登录；若未绑定且允许自动注册 → 创建用户并绑定；否则提示绑定已有账号

解绑

1. 登录用户在账号设置中解绑第三方
2. POST /oauth/unbind 提交 provider
3. 删除 oauth_account 对应记录

七、后台审核与运维

本插件无独立后台管理页，运维在应用中心完成：

八、特殊说明

插件钩子：

• auth_login_extra — 登录弹窗渲染微信/QQ 图标链接

支持的平台常量： wechat、qq（OAuthService::PROVIDERS）

Session 键： oauth_state、oauth_redirect、oauth_intent

安全： consumeState 使用 hash_equals 防 CSRF；safeRedirect 限制站外跳转

与社区集成： 登录成功后写入社区 Session；回调失败跳转登录页并提示

九、推荐上线清单

1. 开放平台应用审核通过
2. 生产环境启用 HTTPS
3. 配置正确的回调 URI
4. 应用中心填写密钥并开启对应平台
5. 测试：新用户授权注册 → 退出 → 再次登录
6. 测试：老用户登录后绑定 → 解绑
7. 确认关闭自动注册时的提示友好

十、常见问题

Q：登录弹窗没有微信/QQ 图标？ 检查总开关、平台子开关、AppID/Secret 是否填写完整。

Q：回调提示 state 无效？ 多为 Session 丢失或跨域；确认同域访问、HTTPS 正常。

Q：redirect_uri 不匹配？ 开放平台配置的回调地址须与 callbackUrl() 生成的一致。

Q：自动注册关闭后新用户怎么办？ 须先用账号密码注册/登录，再在账号设置绑定第三方。

Q：同一微信能否绑多个站？ 每个站点独立 oauth_account；同一 unionid 在不同站可分别绑定。

Q：卸载插件影响已注册用户吗？ 用户账号保留，仅第三方绑定关系丢失。