OAuth2与SSO
页面导读
适用场景适合需要将 FastBee 接入统一身份认证、第三方系统登录或作为 OAuth2 服务端的项目。
前置条件已规划客户端、回调地址、授权范围、用户映射和登出策略。
操作路径系统管理 → 客户端管理 → 创建客户端 → 配置回调地址 → 联调授权流程。
验收点第三方系统可完成授权、获取 Token、读取用户信息，并能按预期退出登录。
一、能力范围
FastBee OAuth/SSO 能力由 fastbee-plugs/fastbee-oauth-server 提供，主要包含：
| 能力 | 接口或路径 | 说明 |
|---|---|---|
| 授权页 | /oauth2/authorize、/oauth/authorize | 授权码模式入口 |
| Token | /oauth2/token、/oauth/token | 获取访问令牌 |
| 登录确认 | /oauth2/doLogin、/oauth2/doConfirm | 登录和授权确认 |
| Token 检查 | /oauth2/check-token、/oauth/check_token | 校验令牌 |
| 撤销令牌 | /oauth2/revoke、/oauth/revoke | 退出或取消授权 |
| 用户信息 | /oauth2/userinfo | 获取当前用户信息 |
| OIDC 配置 | /.well-known/openid-configuration | OpenID Connect 元信息 |
| JWKS | /oauth2/jwks | 公钥信息 |
| SSO | /sso/* | 单点登录相关接口 |
二、客户端配置
客户端配置用于标识接入 FastBee 的第三方应用。
| 字段 | 说明 | 建议 |
|---|---|---|
| Client ID | 客户端唯一标识 | 使用业务系统简称，避免重复 |
| Client Secret | 客户端密钥 | 生产环境定期轮换 |
| Redirect URI | 授权回调地址 | 必须与第三方系统配置完全一致 |
| Scope | 授权范围 | 按最小权限开放 |
| Grant Type | 授权模式 | 常用授权码模式 |
| Token 有效期 | Access Token 生命周期 | 按安全要求设置 |
| Refresh Token | 是否允许刷新 | 长会话场景启用 |
三、授权码流程
四、联调检查
| 检查项 | 正常表现 |
|---|---|
| 回调地址 | 授权后能跳回第三方系统 |
| code | 回调参数中有授权码 |
| token | 第三方系统可换取 access_token |
| 用户信息 | /userinfo 返回当前用户资料 |
| 权限范围 | scope 与客户端配置一致 |
| 登出 | FastBee 和第三方系统退出策略符合预期 |
| 审计 | 登录日志和授权日志可追踪 |
五、常见问题
redirect_uri 不匹配
回调地址必须和客户端配置完全一致，包括协议、域名、端口、路径和斜杠。
Token 获取失败
检查 Client ID、Client Secret、授权码是否过期、授权模式是否启用。
用户信息为空
检查 Token 是否有效、用户是否被禁用、scope 是否包含读取用户信息权限。
单点退出不完整
需要明确是只退出第三方系统、只退出 FastBee，还是两边都退出。不同项目要制定统一策略。
六、二次开发入口
| 类型 | 路径或接口 | 说明 |
|---|---|---|
| 前端页面 | vue3/src/views/iot/clientDetails、vue3/src/views/system/sysclient | 客户端配置 |
| OAuth 模块 | springboot/fastbee-plugs/fastbee-oauth-server | OAuth2 和 SSO 服务端 |
| 客户端接口 | /iot/clientDetails | 客户端管理 |
| OAuth 表 | oauth_client_details、oauth_access_token、oauth_refresh_token | 授权相关表 |
| 系统用户 | sys_user、sys_auth_user | 用户与第三方身份映射 |