简介

本文件面向DouPHP框架，系统化说明第三方平台OAuth2.0授权码模式的完整实现与最佳实践。重点覆盖：

• 授权页面跳转：start()如何生成state并构建授权URL
• 回调处理：finish()如何校验state、用code换取access_token、获取用户信息并完成登录/绑定
• CSRF防护：state机制、会话存储、中间件配合
• 错误处理与异常：配置缺失、state不匹配、授权失败、网络异常等
• 落地流程：通过统一协调服务完成“已关联直接登录 / 未登录自动注册 / 未登录引导绑定”的三种路径

项目结构

DouPHP将第三方登录能力以“插件 + 服务”的方式组织：

• 各平台服务类位于 plugin/<provider>/ 下，提供 start() 与 finish() 两个入口方法
• 统一的第三方登录协调服务 core/service/user/SnsLoginService.php 负责最终的用户登录/绑定逻辑
• 前台/后台CSRF中间件保障表单安全；OAuth流程中主要依赖state+Session进行跨站请求伪造防护

graph TB
subgraph "前端"
U["用户浏览器"]
end
subgraph "DouPHP应用"
A["插件服务<br/>GoogleService / WxloginService / QqService"]
B["协调服务<br/>SnsLoginService"]
C["会话存储<br/>Session"]
D["数据库<br/>user_sns / user"]
end
subgraph "第三方平台"
P["授权服务器<br/>Google / 微信 / QQ"]
end
U --> |1. 访问 start()| A
A --> |2. 生成 state 存入 Session| C
A --> |3. 重定向到授权页| P
P --> |4. 回调 finish()| A
A --> |5. code 换 token / 取用户信息| P
A --> |6. 调用协调服务 resolve()| B
B --> |7. 查询/写入 user_sns| D
B --> |8. 写登录态或跳转绑定| U

核心组件

• 平台服务（start/finish）
  • GoogleService：生成state、构造Google授权URL；回调时校验state、用code换token、拉取用户信息、调用协调服务
  • WxloginService：按UA选择公众号/开放平台凭证，生成state并构造微信授权URL；回调时校验state、换取openid/access_token、拉取用户信息、调用协调服务
  • QqService：生成state并存入Session，构造QQ授权URL；回调使用SDK完成code交换与用户信息获取，再调用协调服务
• 协调服务（SnsLoginService）
  • 根据openid/unionid查找已关联用户，已关联则直接登录
  • 若当前已登录但未绑定，则写入user_sns并进入绑定页
  • 若允许nobind且未登录，则自动注册并登录
  • 否则将sns数据写入session并跳转到绑定页
• CSRF防护
  • 前端/后台CSRF中间件用于表单提交保护
  • OAuth流程通过state+Session防止CSRF

架构总览

下图展示从用户点击“第三方登录”到完成登录/绑定的端到端时序。

sequenceDiagram
participant U as "用户浏览器"
participant S as "平台服务<br/>GoogleService/WxloginService/QqService"
participant O as "第三方授权服务器"
participant C as "协调服务<br/>SnsLoginService"
participant DB as "数据库"
U->>S : 访问 start()
S->>S : 生成 state 并写入 Session
S-->>U : 返回授权URL并重定向
U->>O : 打开授权页并同意授权
O-->>S : 回调 finish()，携带 code/state
S->>S : 校验 state防CSRF
S->>O : 用 code 换取 access_token
O-->>S : 返回 token
S->>O : 用 token 获取用户信息
O-->>S : 返回用户资料
S->>C : 调用 resolve(sns, userProfile, loginIdMode, nobind)
C->>DB : 查询/写入 user_sns
DB-->>C : 结果
C-->>S : 返回最终跳转URL
S-->>U : 重定向到用户中心或绑定页

详细组件分析

GoogleService（Google OAuth2/OIDC）

• start()
  • 读取配置client_id，校验完整性
  • 生成随机state并通过Session保存
  • 构造授权URL（包含response_type=code、scope=openid email profile、prompt=select_account）
  • 返回授权页URL供前端重定向
• finish()
  • 校验state：从Session取出期望值并与回调参数比对，不一致抛出异常（防CSRF）
  • 检查是否存在code，不存在则提示授权失败
  • 用code换取access_token（POST form-urlencoded）
  • 使用Bearer token获取用户信息
  • 组装sns对象（group/apptype/openid/unionid/nickname/avatar/sex），调用协调服务resolve()
• 错误处理
  • 配置缺失、state不匹配、无code、token获取失败、用户信息为空均抛出领域异常并返回用户页

flowchart TD
Start(["开始"]) --> CheckCfg["校验配置 client_id"]
CheckCfg --> GenState["生成 state 并写入 Session"]
GenState --> BuildUrl["构建授权URL"]
BuildUrl --> Redirect["重定向到Google授权页"]
Redirect --> Callback["回调 finish()"]
Callback --> VerifyState{"state 是否匹配?"}
VerifyState -- 否 --> ErrState["抛出异常：非法操作"]
VerifyState -- 是 --> HasCode{"存在 code ?"}
HasCode -- 否 --> ErrAuth["抛出异常：授权失败"]
HasCode -- 是 --> FetchToken["用 code 换 access_token"]
FetchToken --> TokenOk{"获取成功?"}
TokenOk -- 否 --> ErrToken["抛出异常：无法获取授权信息"]
TokenOk -- 是 --> FetchUserinfo["获取用户信息"]
FetchUserinfo --> UserOk{"获取成功?"}
UserOk -- 否 --> ErrUser["抛出异常：无法获取用户信息"]
UserOk -- 是 --> Resolve["调用协调服务 resolve()"]
Resolve --> End(["结束"])

WxloginService（微信登录）

• start()
  • 根据UA判断公众号或开放平台，分别选择对应appid/appsecret
  • 生成state并写入Session
  • 构造微信授权URL（含response_type=code、scope、state）
• finish()
  • 校验state，不存在或失配则抛出异常
  • 用code换取openid与access_token
  • 使用access_token获取用户信息
  • 根据配置决定以openid或unionid作为登录标识
  • 组装sns并调用协调服务resolve()
• 错误处理
  • 配置不完整、state不匹配、无法获取token/用户信息、unionid缺失等场景均抛出异常

flowchart TD
Start(["开始"]) --> UA["识别UA选择凭证"]
UA --> GenState["生成 state 并写入 Session"]
GenState --> BuildUrl["构建微信授权URL"]
BuildUrl --> Redirect["重定向到微信授权页"]
Redirect --> Callback["回调 finish()"]
Callback --> VerifyState{"state 是否匹配?"}
VerifyState -- 否 --> ErrState["抛出异常：非法操作"]
VerifyState -- 是 --> FetchTokenOpenid["换取 openid 与 access_token"]
FetchTokenOpenid --> TokenOk{"获取成功?"}
TokenOk -- 否 --> ErrToken["抛出异常：无法获取授权信息"]
TokenOk -- 是 --> FetchUserinfo["获取用户信息"]
FetchUserinfo --> UserOk{"获取成功?"}
UserOk -- 否 --> ErrUser["抛出异常：无法获取用户信息"]
UserOk -- 是 --> Resolve["调用协调服务 resolve()"]
Resolve --> End(["结束"])

QqService（QQ登录）

• start()
  • 读取配置appid/appkey，校验完整性
  • 启动Session并生成state存入$_SESSION['QC_userData']['state']
  • 构造QQ授权URL（response_type=code、scope=get_user_info）
• finish()
  • 使用官方SDK完成code交换与用户信息获取
  • 组装sns对象（group/apptype/openid/unionid/nickname/avatar/sex）
  • 调用协调服务resolve()
• 错误处理
  • 配置不完整时抛出异常；后续由SDK与协调服务处理异常

flowchart TD
Start(["开始"]) --> CheckCfg["校验配置 appid/appkey"]
CheckCfg --> GenState["生成 state 并写入 Session"]
GenState --> BuildUrl["构建QQ授权URL"]
BuildUrl --> Redirect["重定向到QQ授权页"]
Redirect --> Callback["回调 finish()"]
Callback --> SDKFlow["SDK执行 code 交换与用户信息获取"]
SDKFlow --> Assemble["组装 sns 对象"]
Assemble --> Resolve["调用协调服务 resolve()"]
Resolve --> End(["结束"])

SnsLoginService（统一登录/绑定协调）

• 输入：sns（group/apptype/openid/unionid/nickname/avatar/sex）、userProfile（当前登录用户或null）、loginIdMode（openid或unionid）、nobind（是否允许免绑定自动注册）
• 流程要点
  • 优先按openid/unionid查找已关联用户，找到则直接登录并跳转用户中心
  • 若当前已登录但未绑定该第三方账号，则写入user_sns并进入绑定页
  • 若nobind=true且未登录，则自动注册新用户并登录
  • 否则将sns数据写入session并跳转到绑定页（携带一次性sns_token）
• 数据模型
  • user_sns：记录第三方账号与本地用户的绑定关系
  • user：本地用户表，登录态写入后跳转用户中心

flowchart TD
Start(["开始"]) --> Lookup["按 openid/unionid 查找已关联用户"]
Lookup --> Found{"找到已关联用户?"}
Found -- 是 --> Login["写入登录态并跳转用户中心"]
Found -- 否 --> IsLoggedIn{"当前已登录?"}
IsLoggedIn -- 是 --> Bind["写入 user_sns 并跳转绑定页"]
IsLoggedIn -- 否 --> Nobind{"允许免绑定?"}
Nobind -- 是 --> AutoReg["自动注册并登录"]
AutoReg --> Done(["结束"])
Nobind -- 否 --> SaveSns["将 sns 写入 session"]
SaveSns --> LinkPage["跳转绑定页带 sns_token"]
LinkPage --> Done
Login --> Done
Bind --> Done

CSRF防护与状态验证

• state机制
  • start()生成随机state并写入Session
  • finish()严格校验回调中的state与Session中期望值一致，不一致即拒绝
• 中间件辅助
  • 前台/后台CSRF中间件对表单提交进行令牌校验
  • OAuth回调属于外部回调，通常由路由级豁免CSRF中间件，因此state验证尤为重要
• 历史示例
  • Amazon插件示例中同样采用state+Session方式防止CSRF

依赖关系分析

• 平台服务依赖
  • 配置系统：读取插件配置（client_id/client_secret或appid/appsecret）
  • 会话系统：保存state（Session）
  • HTTP客户端：发起token交换与用户信息查询（cURL或SDK）
  • 协调服务：统一处理登录/绑定逻辑
• 协调服务依赖
  • 数据库：user_sns与user表读写
  • 会话系统：写入sns临时数据或清理推广标记
• 外部依赖
  • 第三方授权服务器：Google/微信/QQ
  • 安全策略：state验证、CSRF中间件、HTTPS

graph LR
G["GoogleService"] --> CFG["配置系统"]
G --> SES["Session"]
G --> NET["HTTP(cURL)"]
G --> COORD["SnsLoginService"]
W["WxloginService"] --> CFG
W --> SES
W --> NET
W --> COORD
Q["QqService"] --> CFG
Q --> SES
Q --> SDK["QQ SDK"]
Q --> COORD
COORD --> DB["数据库(user_sns/user)"]

性能考虑

• 网络请求优化
  • 使用连接复用与合理的超时设置减少HTTP开销
  • 仅在必要时发起用户信息查询（如首次登录或缓存失效）
• 会话与缓存
  • state仅短期有效，避免长期占用Session
  • 可引入短时缓存减少重复token交换（需结合安全性评估）
• 并发与幂等
  • 确保回调接口幂等，避免重复写入user_sns
  • 合理处理并发登录导致的竞态条件（例如唯一索引约束）

故障排查指南

• 配置不完整
  • 现象：start()阶段抛出配置缺失异常
  • 处理：检查插件配置（client_id/client_secret或appid/appsecret）
• state不匹配
  • 现象：finish()校验state失败，抛出“非法操作”
  • 处理：确认state在start()写入Session并在finish()正确读取；检查跨域/代理导致Session丢失
• 授权失败
  • 现象：回调无code或第三方返回error
  • 处理：检查redirect_uri是否与第三方平台注册一致；确认用户未拒绝授权
• 网络异常
  • 现象：token交换或用户信息查询失败
  • 处理：检查SSL证书、DNS、防火墙；增加重试与日志记录
• 登录/绑定异常
  • 现象：协调服务无法写入user_sns或登录失败
  • 处理：检查数据库权限与唯一性约束；核对openid/unionid一致性

结论

DouPHP通过“平台服务 + 协调服务”的分层设计，实现了标准化、可扩展的OAuth2.0授权码模式：

• start()负责生成state并构建授权URL，确保state安全地保存在Session中
• finish()严格校验state，完成code交换与用户信息获取，再通过协调服务统一处理登录/绑定
• 借助state机制与CSRF中间件，有效防范跨站请求伪造
• 协调服务提供清晰的三种落地路径：已关联直接登录、已登录绑定、未登录自动注册或引导绑定

附录：标准OAuth2.0授权码模式参考流程

以下为概念性流程图，便于理解标准授权码模式的关键步骤（与具体代码实现一一对应见上文）：

sequenceDiagram
participant Client as "客户端"
participant App as "应用服务"
participant Auth as "授权服务器"
participant API as "资源服务器"
Client->>App : 访问 /auth/start
App->>App : 生成 state 并保存至会话
App-->>Client : 重定向到授权服务器
Client->>Auth : 打开授权页并同意授权
Auth-->>Client : 重定向回应用回调地址，携带 code 与 state
Client->>App : 访问 /auth/finish
App->>App : 校验 state
App->>Auth : 用 code 换取 access_token
Auth-->>App : 返回 access_token
App->>API : 用 access_token 获取用户信息
API-->>App : 返回用户资料
App-->>Client : 登录成功并跳转

[此图为概念性示意，不直接映射具体源码文件]