Sa-Max 产品白皮书
v1.11.0
让统一认证的交付成本降低 90% 以上
一个项目搞定:同域、跨域、共享Redis、跨Redis、前后端一体、前后端分离、纯 js、vue2、vue3、非 Sa-Token 项目、非 java 项目等架构下的 SSO 认证需求。
支持 Gitee、GitHub、微信、企业微信、飞书、钉钉 6 大平台的快捷登录。
提供用户同步、OAuth2 / OIDC 统一授权认证、开放平台认证、API Key 授权认证。
Get Started一、快速了解 Sa-Max
1.1、Sa-Max 是什么
Sa-Token 商业版 Sa-Max(统一认证综合版),是基于 Sa-Token 搭建的独立统一认证中心,可大大缩短您的项目接入统一授权认证的开发周期。
1.2、Sa-Max 能帮您解决什么
支持 Gitee、GitHub、微信、企业微信、飞书、钉钉 6 大平台的快捷登录。根据平台差异包含:网页重定向授权登录、手机扫码登录、PC 客户端内一键登录等能力,所有平台全程无需改一行代码,在线 UI 化配置即可完成对接。
支持 同域、跨域、共享 Redis、跨 Redis、前后端一体、前后端分离、纯 JS、Vue2、Vue3、非 Sa-Token 技术栈、非 Java 项目 等架构下的单点登录问题。
支持用户信息双向同步:从第三方系统同步至 sso-server,或从 sso-server 同步至第三方系统。支持数据加密传输、参数签名验证,防止请求重放攻击。
支持 OAuth2.0 四种认证模式、Scope 权限签约与用户授权;支持 OIDC 认证模式(id_token、openid、unionid 等),在「用户授权、不暴露密码」的前提下向第三方安全开放受限数据与接口。
提供开放平台 sspx-open门户:第三方企业可自助注册入驻、申请应用、配置回调地址与 Scope 签约;平台方在后台审核把关,将 OAuth2 / OIDC 能力产品化、流程化落地,无需为每接一个合作方单独改代码。
支持 API Key 的签发、授权、校验、回收等全流程管理操作,按 Scope 精确控制接口访问范围。
1.3、Sa-Max 不是一个项目,而是一整套交付物
Sa-Max 并非一个孤立项目,而是一套完整代码:1 个 Java 后端 + 3 个 UI 前端项目 + 11 个对接示例,覆盖从认证中心到各类客户端对接的全部场景。
1.4、在线演示,眼见为实
Sa-Max 在线演示地址:https://sa-max.cn/index-sspx.html,该演示基于最终代码部署演示,所见即所得。
Pain Points二、您是否正面临这些难题?
认证这件事,做对了无人察觉,做错了步步惊心。下面这些场景,您是否似曾相识?
多系统切换频繁输入账号密码,使用体验极差,员工抱怨不断,用户流失严重。
想接 微信、企微、飞书、钉钉 的快捷登录?每个平台官方文档又散又绕,对接一次踩坑数天乃至数周,浪费研发精力。
前后端分离、微服务、跨Redis、同域、跨域……不同架构下认证方案千奇百怪,难以打通。
自研 SSO / OAuth2 耗费数月,技术门槛高、踩坑多,严重拖慢项目交付周期。
第三方合作伙伴想要接入?OAuth2 协议陌生,API 授权没有安全方案,合作对接难以落地。
市面产品要么 SaaS 数据不安全,要么加密 Jar 看不到源码,业务定制更是无从下手。
您缺少的,正是一个开箱即用的:统一认证中心系统
Build vs Buy三、为什么企业应优先采购而非自研
统一认证是高门槛、低容错的基础设施:做得再好,用户也只觉得「本就该如此」;做差一点,却可能是安全事故。它不会成为您产品的卖点,却会消耗大量研发精力 —— 把攻坚留给核心业务,比在这里反复造轮子更值得。
3.1、自研 vs 采购 · 九大维度对比
| 对比维度 | 从零自研 | 采购 Sa-Max |
|---|---|---|
| 交付周期 | 数月乃至数年,反复返工 | 读懂文档即可对接,按天计 |
| 研发成本 | 资深工程师长期投入,人力成本高 | 一次买断,省去数月人力 |
| SSO 架构覆盖 | 通常只解决眼前一种架构 | 同域 / 跨域 / 跨 Redis / 前后端分离 等全覆盖 |
| 第三方登录 | 六平台规则各异,回调 / 扫码 / 联调踩坑多 | 6 平台对接开箱即用 + 专属踩坑记录文档 |
| OAuth2 / 开放平台 | 协议复杂,自研极易出错 | 开箱即用,含开放平台与审核流 |
| 安全防护 | 易遗漏,单点疏忽即埋雷 | 内置完善安全机制,久经实战检验 |
| 源码与二开 | 完全自有 | 全源码交付、无加密 Jar、可自由二开 |
| 持续维护 | 需自行长期跟进与修补 | 服务期内持续更新 + 专业售后技术支持 |
| 试错风险 | 坑都要自己踩一遍 | 已服务 1000+ 付费主体,久经验证 |
结论很清楚:除非认证本身就是您的核心商业模式,否则把宝贵的研发资源投入到真正能形成差异化竞争力的业务上,认证这一层交给专业方案,是更划算的选择。
3.2、自研的成本与工期
很多团队在立项时容易低估一个统一认证系统的复杂度。它看上去只是"登录 + 退出",但真正落地时,却发现要踩的坑越来越多:
- 异构系统的交叉整合:同域、跨域、共享Redis、跨Redis、前后端一体、前后端分离、纯js、vue2、vue3、非 Sa-Token 技术栈、非 java 项目 各有各的坑;
- 用户数据双向同步:已有系统用户是否需要迁移?新增用户如何同步?用户资料变动子系统如何实时感知?
- SSO 应用管理:新系统如何无痛接入?已有系统如何管理?如何控制不同用户可进入不同的系统?
- SSO 会话管理:全端注销、单应用注销、单浏览器注销、单客户端注销等各类注销的细节控制;
- 第三方社交登录:Gitee、GitHub、微信、企业微信、飞书、钉钉 六个平台 OAuth 规则各不相同,回调登记、扫码登录、PC 客户端自动登录等各有一套坑;
- OAuth2 授权设计:授权码、隐藏式、密码式、客户端凭证式,什么场景下使用哪种模式?什么场景下需要什么参数?OIDC 的 id_token、openid、unionid 各解决什么问题?
- 开放平台:第三方平台想要接入?不是对接个接口就能完事,这背后是应用的注册、审核、权限签约、回调地址白名单管理等一整套流程的复杂设计。
- API Key 管理:API Key 的签发、授权、校验、回收等全流程管理,按 Scope 精确控制接口访问范围。
把这些"硬骨头"折算成人力:以一支中等规模团队(2~3 名后端 + 1~2 名前端)从零做一套"够用"的统一认证中心为参考,大致投入如下:
| 自研模块 | 主要工作范围 | 预估人月 |
|---|---|---|
| SSO 核心 | 认证中心搭建、ticket 机制、同域 / 跨域适配、会话共享 | 2~3 人月 |
| 第三方登录 | Gitee / 微信 / 企微 / 飞书 / 钉钉 等平台对接、账号绑定解绑、各平台联调与踩坑文档 | 1~1.5 人月 |
| OAuth2 / OIDC | 授权码流程、Token 签发与校验、Scope 控制、OIDC 支持 | 2~3 人月 |
| 管理后台 | 用户、应用、授权数据、日志统计等可视化界面 | 2~3 人月 |
| 安全防护 | 授权重定向地址校验、CSRF、CORS、关键接口防刷、防重放攻击 | 1~2 人月 |
| API Key 体系 | 签发、Scope 定义、校验、回收 | 1.5~2 人月 |
| 用户同步 | 双向同步、资料变动实时感知、加密传输、签名校验 | 1.5~2 人月 |
| 文档与测试 | 开发 / 部署 / 接口文档、集成测试、安全测试 | 1~2 人月 |
| 合计 | 且仅是"够用"版本,尚未计入后续持续迭代 | 约 12~18.5 人月 |
按一线城市中级工程师约 2.5 万元 / 月 折算,自研一套"够用"版本的人力成本约 30 万 ~ 46 万元、工期 6~9 个月,且交付后仍要长期跟进协议升级与安全修补。而采购 Sa-Max 最低数天内即可对接,一次性投入通常只是自研的零头 —— 这笔账并不难算。
3.3、产品功能完整度
自研版本往往"先解决眼前的一种场景",等到新业务、新架构、新合作方接入时,才发现当初的设计撑不住,只能继续加代码、改架构。当技术债务积累到一定程度,就只能推倒重来。
即使各种艰难拼凑,反复修改,到最后的成品也往往是 只见其形,无有其神 —— 统一认证授权、开放平台、多架构适配与安全防护等关键能力,要么缺位,要么粗糙难用。
Sa-Max 的功能边界,是在 服务1000+付费主体 的过程中被真实需求反复打磨出来的:
- 覆盖 10+ 种对接场景的示例工程,每新接一个系统几乎都有对应范本可抄;
- SSO + 第三方登录 + OAuth2/OIDC + API Key 多种认证模型齐备,覆盖内部应用、第三方应用、社交快捷登录、应用级授权、账号级授权等场景;
- 六大平台(Gitee、GitHub、微信、企业微信、飞书、钉钉)第三方快捷登录开箱即用,配套专属踩坑记录文档,无需从零摸索各平台对接差异;
- 三套可视化前端(后台管理、平台中心、开放平台),分别面向管理员、用户与第三方合作商,应用维护、统一登录、授权自助与对接申请均可界面化完成;
- 消息通知、SSO 登录日志、验证码防刷、文件上传等基础能力随包附带。
3.4、安全性问题
安全问题是最容易被疏忽的,而它的复杂度恰恰集中在最隐蔽的细节里。
我们举一个简单的例子,在 SSO 或 OAuth2 对接时,仅一个授权重定向的动作,就至少需要做到以下安全设计:
- 1、授权重定向下放的授权依据必须是 ticket 票据或 code 码,而不能是 token 凭证。
- 2、每次授权产生的 ticket 码都必须是随机的、不可预测的。(code 授权码同理,下不赘述)
- 3、每个 ticket 码都必须用完即废、不可二次复用(防止重放攻击:攻击者截获 ticket 后无法再次使用完成登录)。
- 4、每个 ticket 码的有效期必须极短,例如五分钟后自动失效,即使该 ticket 码尚未使用。
- 5、每次授权产生新的 ticket 码,旧 ticket 码必须立即作废,即使旧 ticket 码尚未使用。
- 6、每个授权 ticket 码必须和应用+用户做到唯一性绑定,不能跨应用、跨用户使用。
- 7、授权重定向地址必须是后台已备案的白名单地址,不能向任意地址下放授权(防止 ticket 码劫持攻击:授权凭证不会被重定向到攻击者控制的站点)。
- 8、备案的授权重定向地址通配符 * 只能出现在末尾,不能出现在中间,防止通过路径或域名构造虚假地址,绕过白名单校验。
- 9、授权重定向地址不能出现 @ 字符,防止利用 @ 构造虚假 URL 地址绕过白名单校验。
- 10、OAuth2 场景下,本次授权申请的所有 Scope 权限必须已签约,否则需要立刻阻断授权。
- 11、OAuth2授权重定向的 state 参数必须原样返回,且在客户端做好一一对应的校验(防止 OAuth CSRF 攻击:攻击者无法将他人授权产生的 code 绑定到受害者当前发起的登录流程)。
以上仅是 授权重定向一个环节 就需要守住的要点。自研团队往往只覆盖前几项"能跑就行",越往后越容易遗漏 —— 而每漏一项,都可能成为被攻击者利用的缺口。
搭建一个固若金汤的系统需要上千把锁,而攻击者往往只需攻破其中最弱的一把。
Sa-Max 以 GitHub 18k+ star 的 Sa-Token 为鉴权内核夯实底座;而前文所列防线均由 Sa-Max 商业版全部内置。产品一贯遵循「对前端传入数据零信任」的安全原则,把这些坑提前替您填好。
3.5、一个真实的安全案例
安全问题不是只有小厂才犯,大厂也会翻车!
2021 年,我们在研发 Sa-Token SSO 组件时,为尽可能覆盖更多对接场景,对市面主流 SSO 框架及多家互联网大厂的统一登录与 OAuth2 授权实现,做了逐一调研与实测。
在实测阶段,我方团队发现一个拥有近千万用户的大厂公司,其网站存在授权重定向漏洞,该网站的 SSO 登录未对授权重定向地址进行合法性校验,导致其可以将 code 授权码下发到任意第三方网址。
此漏洞造成的直接后果就是:我可以精心构建一个钓鱼地址,只要别人点击这个地址,我就能无感的登录他的账号。
与同事进行漏洞复现,成功在我的电脑登录他的账号:
此漏洞在 2021 年 6 月下旬发现,到 7 月下旬时,官方仍未修复,于是我尝试联系官方人员提交漏洞反馈:
从漏洞发现到提交,其官方网站在一个月时间内均处于漏洞状态(实际的漏洞时间可能更长,只是没有发现),在提交反馈后,官方又用三天时间确认漏洞,而后又用了四天时间进行修复。
这个修复时间,说慢不算慢,但也绝对称不上快。
其实我挺能理解的,大厂公司内部的各个产品都需要快速升级迭代,每个人的开发任务都安排的很满,能抽出时间在七天内确认漏洞并修复,已经是很不容易的一件事了。
毕竟很多时候,我们都会有一种侥幸心理:就算系统有漏洞,它也已经安安稳稳的跑几年了,就算耽搁十天半个月不去修复,也应该不会出现什么问题。
但 —— 我们需要正视的一点是:与其在漏洞发现后压缩工期手忙脚乱的去修复,我们为何不在项目开发阶段就把这些漏洞消灭于无形呢?这便是采购 Sa-Max 这类久经验证的成熟认证系统其价值所在。
《韩非子》里有个典故:扁鹊兄弟三人,长兄擅治未病、次兄擅治将病,唯有扁鹊治已病却名闻天下。世人只看见「妙手回春」的戏剧性,往往看不见「防患未然」的含金量。统一认证的安全建设也是如此 —— redirect 白名单、ticket 一次性消费等防线若在开发阶段就做扎实,系统可能常年「无声无息」地运行,换不来轰轰烈烈的抢救故事,但这恰恰是它最值钱的地方。
正所谓:善战者无赫赫之功。真正高明的安全建设,不是出了事再当英雄,而是让攻击者连舞台都没有。
Features四、产品功能介绍
以下按模块依次介绍 Sa-Max 的核心产品能力。
4.1、三大平台
Sa-Max 共包含三大平台:后台管理(管理员)、平台中心(员工 / 用户)、开放平台(第三方企业),各司其职、入口分离。
| 平台 | 工程名 | 主要使用者与职责 |
|---|---|---|
| 后台管理 | sspx-admin | 平台运营与 IT 管理员:应用接入、用户与权限、第三方登录配置与绑定记录、开放平台审核、API Key 与系统配置、日志审计与在线会话处置等。 |
| 平台中心 | sspx-center | 企业内部员工或 C 端用户:统一登录入口(含 Gitee / GitHub / 微信 / 企微 / 飞书 / 钉钉 六大平台快捷登录)、工作台进入各子应用、第三方账号绑定解绑、已授权 OAuth2 应用与 API Key 自助管理等。 |
| 开放平台 | sspx-open | 外部合作企业 / 开发者:注册入驻、申请应用、配置回调与 Scope 签约、查看已授权数据,完成 OAuth2 对接。 |
后台管理(sspx-admin):面向管理员的全局管控台,覆盖监控、用户、应用、第三方登录、开放平台、API Key、系统配置等能力:
平台中心(sspx-center):面向员工 / 终端用户的统一身份门户,「我的应用」工作台、六大平台快捷登录与个人账号绑定、OAuth2 应用授权自助均在此完成:
开放平台(sspx-open):面向第三方企业的对外门户,完成应用申请、OAuth2 能力对接与权限签约等开放生态协作:
4.2、一键配置对接6大平台登录
用户在平台中心 sspx-center 统一登录页可选用 Gitee、GitHub、微信、企业微信、飞书、钉钉 六大平台快捷登录,降低注册与登录门槛;管理员在后台填写各平台 OAuth 凭证、一键开关与排序,无需改代码即可完成对接。
- 1、在第三方开放平台创建应用,配置回调地址 / 回调域名,获取 Client ID、Secret 等凭证;
- 2、把第三方平台的凭证信息回填到 Sa-Max 后台管理「第三方平台配置」中;
全程无需改一行代码,在线 UI 化配置即可完成对接。
各平台支持能力
- Gitee:支持 网页重定向授权登录、账号绑定、解绑。
- GitHub:支持 网页重定向授权登录、账号绑定、解绑。
- 微信:支持 手机扫码登录、账号绑定、解绑。
- 企业微信:支持 手机扫码登录、网页重定向授权登录(企微PC客户端内)、PC 客户端内自动登录、账号绑定、解绑。
- 飞书:支持 手机扫码登录、网页重定向授权登录、PC 客户端内自动登录、账号绑定、解绑。
- 钉钉:支持 手机扫码登录、网页重定向授权登录、PC 客户端内自动登录、账号绑定、解绑。
平台中心登录页:六大第三方平台图标一键登录、个人中心第三方账号绑定与解绑:
后台管理统一配置六大平台:Logo 图标顺序、凭证填写、开放策略、回调地址一键复制等
第三方绑定记录:管理员可在后台按平台筛选、全局检索与审计全部绑定关系;用户体系同步记录账号来源(来源方式 / 来源详情 / 注册 IP),第三方登录与绑定行为均可追溯:
六个平台的 OAuth 规则表面相似、细节千差万别——回调地址登记粒度不同、有的禁端口有的要域名验证、企微要 IP 白名单、飞书钉钉须发版才能用……初次对接时,光是翻各平台官方文档、本地联调踩坑,往往就要耗掉数天乃至数周。
Sa-Max 提供六个平台的分步图文教程,踩坑经验开箱即阅 —— 照着文档逐步操作,通常几十分钟即可跑通一个平台,让您把精力留给自己的业务开发,而不是耗在各平台对接差异的细枝末节上。
以微信篇为例:除分步对接教程外,还附有支持能力对照、浏览器兼容性测试报告等产品边界说明,让您对产品能力与限制心中有数,合理规划系统设计:
4.3、SSO 单点登录
SSO 是 Sa-Max 的根基能力:一处登录,全端通行。基于 Sa-Token SSO 三种模式搭建,覆盖企业中几乎所有常见架构,绝大多数场景无需二次开发即可直接开始对接。
- 模式一(同域、同 Redis):使用 Cookie 共享会话机制。适合多个系统可以部署在同一主域名的情形。
- 模式二(跨域、同 Redis):URL 重定向传播授权。适合应用端可以和认证中心连接同一 Redis 的情形。
- 模式三(跨域、跨 Redis):使用 HTTP 请求查询会话。托底模式,子系统与认证中心彻底解耦。
- ReSdk 模式:重写框架部分接口,适合应用端不使用 Sa-Token 技术栈的项目。
- NoSdk 模式:使用 HTTP 工具类调用接口对接,适合应用端不使用 Sa-Token,或非 Java 语言的项目。
- 前后端分离:三种模式 + ReSdk 模式 + NoSdk 模式,均可适配前后端分离项目,提供纯 js、vue2、vue3 架构的对接示例。
Sa-Max 提供各种登录方式示例:超链接直接登录、访问页面触发登录、调用 Ajax 触发登录。
4.4、SLO 单点注销
与 SSO 相对应,SLO 解决的是一处注销,全端下线的问题。Sa-Max 在打通登录链路的同时,也提供了粒度可控的多场景注销能力,可按业务需要精细选择退出范围。
- 全端注销:用户在所有已登录应用中统一下线;
- 单端注销:用户只在当前客户端单独注销;
- 单应用注销:仅退出当前应用,其它应用保持登录态;
- 单浏览器注销:当前浏览器下全部应用统一下线;
Sa-Max 提供各种注销方式示例:访问超链接直接注销、调用 Ajax 触发注销。
4.5、应用管理
所有接入认证中心的子系统都以"应用(Client)"的形式被统一登记与管理。管理员可在后台为每个应用维护基础信息、对接配置与状态,新增 / 调整一个接入系统无需改代码、改配置文件,在界面上即可完成。
应用是访问控制与开放授权的基本单元 —— 清晰的应用台账,是统一认证可治理、可审计的前提。
4.6、访问控制管理
解决一个核心问题:决定哪个用户可以登录哪个系统。Sa-Max 在应用管理中将每个应用标记为公开或私有,并在此维护用户与应用的访问关系。
- 公开应用:公开应用默认所有用户均可登录,你可以在此设定禁止哪个用户登录;
- 私有应用:私有应用默认所有用户均不可登录,你可以在此设定允许哪个用户登录;
- 跟随应用配置:未对此用户单独设定时,是否可登录由该应用是公开还是私有来决定。
当一个用户不具有权限访问一个应用时,他在自己的工作台也无法看到这个应用。
当他尝试强行登录此应用时,将会被阻断登录。
4.7、SSO 登录日志
SSO 打通多系统后,谁在什么时间、从哪个应用、用什么设备与 IP 完成了登录,都需要可查、可审计。Sa-Max 会对各项 SSO 登录行为做详细记录,管理员在后台即可按账号、应用、Token、IP 等条件检索,异常登录有迹可循。
- 记录维度完整:登录账号、登录应用、登录 IP、设备信息、本次登录 Token、登录时间等字段一应俱全;
- 覆盖 SSO 全链路:认证中心登录、各子应用 SSO 登录等均纳入同一套日志体系;
- 便于运营与安全审计:支持查询、导出与详情查看,配合访问控制与在线用户管理,形成闭环。
后台 sspx-admin「用户管理 → 登录日志」集中展示全平台 SSO 登录记录,各项字段清晰可查:
4.8、在线用户管理
除登录日志外,管理员还需要实时掌握当前仍在线的会话,并在账号异常、设备遗失、安全事件等场景下迅速处置。Sa-Max 提供在线用户管理能力:可查看会话创建 / 失效时间、当前登录客户端数量,并对指定账号执行踢下线或强制注销。
- 踢下线:结束当前在线会话,用户需重新登录方可继续访问;
- 强制注销:在踢下线基础上进一步清理会话凭证,适用于更彻底的安全止损;
- 与 SSO / SLO 协同:配合单点注销能力,可按运营需要控制下线范围。
后台「在线用户」列表汇总当前在线账号,可直接对单个用户执行踢下线或强制注销:
同一账号若在多个客户端同时登录,可展开查看各客户端会话明细,并针对其中某一个客户端单独踢下线或强制注销:
4.9、用户同步
很多企业并非从零开始,而是已有若干存量系统、各自维护着一份用户数据。Sa-Max 提供双向用户同步方案,帮助新老系统平滑打通:
- 从认证中心同步到第三方系统:当 sso-server 发生用户数据变动时,实时广播到其它第三方系统;
- 从第三方系统同步到认证中心:当第三方系统发送用户数据变动时,实时推送到 sso-server 系统。
无需更改认证中心代码,在后台管理界面即可直接配置同步规则(接收推送 / 向外广播):
在推动端 / 接收广播端,使用极简的代码即可完成对接:
4.10、OAuth2 / OIDC 授权
OAuth2 是 Sa-Max 对外开放能力的协议基石。它解决的核心问题是:在用户明确授权的前提下,让第三方应用安全地获取受限信息或调用受限接口,而无需向第三方暴露用户的账号密码 —— 就像微信、GitHub 第三方登录那样。
四种授权模式,覆盖全部对接场景
不同的对接方与信任级别,适用不同的授权模式。Sa-Max 完整支持 OAuth2.0 规范定义的四种标准模式:
| 授权模式 | 适用场景 | 流程要点 |
|---|---|---|
| 授权码模式 Authorization Code | 最常用、最安全。适合有后端的第三方 Web 应用。 | 先回调拿到一次性 code,再由后端用 code + client_secret 换取 token,token 不经过浏览器,最大限度防泄露。 |
| 隐藏式 Implicit | 纯前端 / 无后端的 web 站。 | 授权后直接在重定向地址中返回 token,省去换取步骤,简化但安全性相对较低。 |
| 密码式 Password | 高度互信的第一方应用(如自家 App)。 | 用户把账号密码直接交给应用,应用凭此换取 token,仅限信任场景使用。 |
| 客户端凭证式 Client Credentials | 无用户参与的服务端对服务端(机器对机器)调用。 | 应用以自身 client_id + client_secret 直接换取 token,代表应用自身而非某个用户。 |
标准授权流程
以最常用的授权码模式为例,一次完整授权的交互流程如下,其余三种模式均为此流程的精简变体:
整个流程内置了完善的安全防线:redirect_uri 白名单校验、state 防 CSRF、code 一次性消费且短时效、scope 必须已签约方可授权,全程遵循"对前端传入数据零信任"的原则。
OIDC / OpenID Connect:在授权之上叠加"身份"
OAuth2 解决的是"授权"(这个应用能拿到哪些数据),而 OIDC(OpenID Connect) 是在 OAuth2 之上扩展出的"认证"层,解决"这个用户到底是谁"的问题。Sa-Max 支持 OIDC 模式,在常规 token 之外额外下发一枚 id_token,第三方应用可由此可靠地识别已登录用户的身份标识。
- openid(应用内唯一标识):同一个用户,在不同的第三方应用下会得到不同的 openid。它做到了应用间的身份隔离 —— A 应用拿到的 openid 无法在 B 应用复用,避免第三方之间相互撞库、关联用户。这是单个应用识别"老用户/新用户"的依据。
- unionid(同主体下唯一标识):当多个应用同属同一开放平台主体(同一家公司名下的多个网站)时,同一用户在这些应用下会得到相同的 unionid。它让企业能够在自家产品矩阵内打通同一用户的身份,做到"一次注册、多端互认"。
举例:一家公司有"商城 + 短视频 + 论坛"三个接入应用,靠 unionid 即可识别"这三处来的是同一个人",从而打通会员体系;而对外部不同的合作伙伴,则各自只能拿到隔离的 openid,互不关联,保护用户隐私。
4.11、开放平台
如果说 OAuth2 / OIDC 是"协议能力",那么开放平台 sspx-open 就是把这套能力产品化、流程化的对外门户。它让外部企业可以像入驻微信开放平台、支付宝开放平台 那样,自助申请应用、配置参数、申请权限、提交审核,而平台方管理员则在后台对每一个申请进行人工把关 —— 整个过程界面化、有审计、安全可控,无需为每接一个合作方都改代码。
第三方对接:从注册到上线的一整套流程
| 阶段 | 操作方 | 关键动作 |
|---|---|---|
| ① 注册入驻 | 第三方公司 | 在开放平台 sspx-open 注册开发者账号,完善主体信息,成为可申请应用的合作主体。 |
| ② 申请应用 | 第三方公司 | 创建应用、填写应用名称 / 简介 / Logo、配置回调地址(redirect_uri)白名单,提交申请资料。 |
| ③ 应用审核 | 平台管理员 | 在后台 sspx-admin 根据提交资料审核应用是否合规,通过后下发 client_id 与 client_secret。 |
| ④ 权限签约 | 第三方 + 管理员 | 第三方按需申请所需 scope 权限并签约,管理员审核授予的能力边界(详见 4.12 权限签约)。 |
| ⑤ 对接联调 | 第三方公司 | 凭下发的凭据按 OAuth2 流程发起授权,引导用户确认授权、回调换取 token、调用开放 API。 |
| ⑥ 上线运营 | 双方 | 正式对外提供服务;授权记录全程留痕,管理员可随时审计、停用违规应用。 |
这一整套流程背后,是应用注册、资料审核、回调白名单管理、凭据签发、权限签约、授权确认、记录审计等多个环节的协同 —— 它们都已在 Sa-Max 中开箱即用,无需自研。
第三方企业在开放平台自助创建应用、填写资料并提交申请,是开放对接的起点:
平台管理员在后台审核第三方提交的应用,通过后签发 client_id / client_secret,把控接入质量:
后台审核通过后,第三方企业可在开放平台查看自己已申请的全部应用,凭据与对接状态一目了然:
进入具体应用后,可在「应用信息」页维护应用名称、Logo、简介、主页等对外展示资料:
在「开发配置」页查看 client_id / client_secret,并配置授权回调地址(redirect_uri)白名单,是 OAuth2 对接的关键参数:
4.12、权限签约
权限签约是开放平台安全性与可控性的核心机制。它要回答的问题是:一个第三方应用,到底被允许获取哪些数据、调用哪些接口?答案不是"全有或全无",而是通过 scope(权限范围)做到颗粒度精确、按需开放、最小授权。
所谓 scope,就是把平台对外开放的每一项能力(如"读取用户昵称头像""获取手机号""读取订单列表")拆成一个个独立的权限项。第三方应用申请并签约了哪些 scope,就只能拿到哪些能力 —— 未签约的 scope,应用则无法获取到相应授权。
签约申请、审核、对接的完整流程
| 环节 | 说明 |
|---|---|
| ① 申请签约 | 第三方在开放平台浏览可申请的 scope 列表,按业务实际需要勾选所需权限项,提交签约申请(并可附说明用途)。 |
| ② 管理员审核 | 管理员在后台审核该应用申请的每一项 scope 是否合理:是否与其业务匹配、是否涉及敏感数据、授予后风险是否可控,可逐项批准或驳回。 |
| ③ 签约生效 | 审核通过后,该应用即与对应 scope 建立"签约关系",获得这些 scope 对应的能力边界。 |
| ④ 授权对接 | 用户授权时,授权确认页会明示该应用申请的 scope 清单;授权后,第三方仅能在已签约 scope 范围内调用开放 API,越界调用一律被拒绝。 |
| ⑤ 变更 / 解约 | scope 需求变化时可追加申请、重新审核;不再需要的权限可解约回收,能力边界随之收紧。 |
以下按「定义权限 → 申请签约 → 后台审批 → 用户授权 → 换取凭据」顺序,展示权限签约与授权对接的关键界面:
平台方先在后台 sspx-admin 统一配置系统对外开放的全部 Scope(分组、敏感等级与能力说明),作为后续签约与授权的能力目录:
第三方企业在开放平台进入应用的「签约权限」页,按业务需要浏览权限项,对未签约的 Scope 提交申请:
管理员在后台「权限签约申请」中逐条审批,结合资质说明与敏感等级,对每一项 Scope 批准或驳回:
签约审核通过后,应用方可引导用户发起 OAuth2 授权;用户在平台中心确认页查看并同意本次申请的 Scope 清单:
用户确认授权后,第三方凭回调获得的 code 换取 access_token,并按已签约的 scope 返回 openid、unionid、userid 等授权数据:
对接目标:最小授权、按需开放
- 双重门槛:一项数据被第三方拿到,需同时满足"应用已签约该 scope"+"用户已确认授权"两道关卡,缺一不可;
- 能力边界清晰:每个应用能做什么一目了然,便于审计与责任界定;
- 降低泄露面:即便某第三方凭据泄露,攻击者也只能触及其签约范围内的能力,不会殃及全量数据;
- 授权时必校验:本次授权申请的所有 scope 必须已签约,否则立即阻断授权(呼应 3.4 节安全要点第 10 条)。
4.13、授权记录审计
开放授权一旦放开,"谁、在什么时候、授权了哪个应用、开放了哪些 scope"就必须可查、可追溯。Sa-Max 对每一次用户授权完整留痕,同时面向用户侧与管理侧分别提供自助与审计能力;用户或管理员亦可一键解约,权限即时收回、止损迅速。
- 授权记录留痕:每一次用户对第三方应用的授权,都记录授权时间、应用、授予的 scope、授权方式等,可按用户 / 应用维度检索;
- 用户侧自助(平台中心 sspx-center):用户可查看"我已授权过哪些应用"、各应用拿到了哪些权限,并支持一键解约,随时收回授权;
- 管理侧审计(后台 sspx-admin):管理员可全局查询授权数据与授权日志,定位异常授权、配合安全审计与合规要求;
- 解约即时生效:用户或管理员解除授权后,第三方应用对应访问能力立即失效,权限边界随之收紧。
完善的授权审计,既是安全合规的底线要求,也是用户信任的基础 —— 授权行为全程可查,用户能清楚看到自己授权了谁、并能随时解约收回,平台对外开放才真正"放得开、也收得回"。
以下分别从用户、第三方企业、平台管理员三个视角,展示授权记录的查询与管理界面:
用户视角(平台中心 sspx-center):查看「我已授权的第三方应用」、各应用获得的 Scope 与有效期,并支持一键解除授权:
第三方企业视角(开放平台 sspx-open):在应用「已授权数据」中查看哪些用户已授权本应用、授权时间及 OpenId 等对接标识:
后台管理员视角(sspx-admin):全局检索授权记录,按应用、用户、Grant_Type、Scope、令牌与授权时间审计追溯:
4.14、API Key 授权
面向服务端后台、自动化脚本、定时任务与系统间集成 等"无人值守"场景,Sa-Max 提供完整的 API Key 能力。不同于需要用户交互的 OAuth2,API Key 是一种长效、可控的免登录凭证。
- 签发:一键生成带
AK-前缀的密钥,支持后台签发与用户自助创建(可自由配置前缀); - 授权:为每个 API Key 绑定 Scope 权限列表与到期时间,精确控制可访问的接口范围;
- 校验:调用受保护接口时自动鉴权与权限判定,越权调用被拒绝;
- 回收:支持禁用、删除,并在到期后自动失效,泄露风险可随时止损。
以下按「定义 Scope → 用户创建 API Key → 分配权限 → 调用校验 → 后台治理」顺序,展示 API Key 能力的关键界面:
平台方先在后台 sspx-admin 的「API Key 权限」中统一配置可供申请的 Scope 项(分组、等级与能力说明):
用户在平台中心 sspx-center 可自助「创建一个 API Key」,密钥归属当前登录账号,便于脚本与自动化场景使用:
创建 API Key 后,可为不同 API Key 勾选不同的 Scope 组合,做到「一把钥匙开一扇门」:
仅当 API Key 处于生效状态且具备接口所需的 Scope 时,调用才会成功;平台中心提供联调测试,便于创建后即时验证:
管理员在后台「API Key 管理」中可查看全平台用户创建的所有 API Key,并按需修改、删除、禁用,统一治理风险:
4.15、UI 化便捷配置
认证中心的许多全局性、影响面大的参数 —— 登录策略、用户同步规则、验证码防刷、开放平台 Token 时效、表格展示视图等 —— 都不必再翻配置文件或改库。Sa-Max 在后台 sspx-admin「系统配置」 中提供统一的 UI 视图,管理员点选、填表、保存即可生效,大幅降低运维与二开门槛。
除本节所示的系统级配置外,前文各能力模块(应用、访问控制、用户同步、第三方登录、开放平台、API Key 等)也均在对应菜单下提供可视化维护界面;三套前端(后台管理、平台中心、开放平台)基于 Vue 3 + Vite 8 + Element Plus 构建,开箱即用。
系统基本信息:动态配置系统名称、Logo、版本号与更新说明等对外展示信息(本配置仅作用在后台管理端):
全局参数:注册开关、登录方式、新用户默认头像等全站行为一键配置:
用户同步配置:在界面中维护接收推送 / 向外广播规则,与 4.9 用户同步能力对应,无需改代码:
验证码防刷配置:图形验证码、短信 / 邮箱验证码的发送频控与防刷策略:
开放平台配置:第三方应用申请策略、审核方式、Access-Token / Refresh-Token 时效等 OAuth2 相关全局项:
第三方登录配置:Gitee、GitHub、微信、企业微信、飞书、钉钉 六大平台的凭证填写、开放策略、登录页图标开关与拖拽排序,均在后台「第三方登录 → 第三方平台配置」可视化维护;
表格视图配置总览:集中查看各业务列表页的表格列、检索项等视图配置入口,便于统一维护:
4.16、在线演示
以上仅为 Sa-Max 认证授权相关核心能力的介绍,产品中仍有大量基础功能未在本章逐一展开,例如:Redis 监控台、SQL 监控台 / Druid、API 请求日志、验证码发送记录、用户列表与回收站、数据走势 —— 注册与登录统计图表、消息通知 等。
建议您通过我们部署的在线演示进一步了解:https://sa-max.cn/index-sspx.html
Tech Stack五、架构与技术栈
Sa-Max 采用前后端分离架构:后端基于 Spring Boot 4 + Sa-Token 1.45,三套 UI 前端统一采用 Vue 3 + Vite 8 主流技术栈。整套交付包含 1 个后端、3 个前端、11 个对接示例,版本持续跟进社区最新 LTS,降低长期维护成本。
5.1、后端(sspx-server)
基于 Spring Boot 4 构建,认证内核 Sa-Token 升级至 v1.45,数据层与 JSON 序列化等依赖已同步适配。
| 技术 | 说明 |
|---|---|
| Java 17 | 后端开发语言,JDK 17 LTS |
| Maven | 项目构建与依赖管理 |
| Spring Boot 4 | 后端基础框架,基于 Spring Framework 7 |
| Sa-Token 1.45 | 认证授权核心,承载 SSO、OAuth2 / OIDC、API Key、第三方登录等 |
| sa-token-redis-template | Sa-Token 会话与 Token 持久化至 Redis |
| sa-token-forest | 对外 HTTP 调用,如用户同步回调 |
| MyBatis-Plus | ORM 与数据库访问,适配 Spring Boot 4 |
| PageHelper | 列表分页 |
| MySQL 8.4 | 业务数据存储,兼容 8.4+ 语法与特性 |
| Druid | 数据库连接池,附带 SQL 监控 |
| Redis | 会话、Token、票据等高频缓存 |
| Jackson | JSON 解析与序列化 |
| Hutool | 常用工具类库 |
| Lombok | 简化实体与样板代码 |
| UserAgentUtils | 解析浏览器、设备信息(登录日志等) |
| AJ-Captcha | 滑块行为验证码 |
| JavaMail | 邮件验证码发送 |
5.2、前端(sspx-admin / sspx-center / sspx-open)
三套前端工程统一技术栈,Vite 8 极速构建,Vue Router 5 管理路由,开箱即用、风格一致。
| 技术 | 说明 |
|---|---|
| Vue 3 | 前端 UI 框架,组合式 API |
| Vue Router 5 | 路由与页面导航 |
| Pinia | 全局状态管理 |
| Vite 8 | 本地开发与生产构建,极速 HMR |
| Element Plus | 后台 UI 组件库 |
| @element-plus/icons-vue | Element Plus 图标 |
| @layui/layer-vue | 弹窗、确认框等交互 |
| Axios | 请求 sspx-server 接口 |
| NProgress | 路由切换顶部进度条 |
| js-cookie | Cookie 读写 |
| crypto-js | 前端加解密 |
| @vueuse/core | 组合式 API 工具集 |
| mitt | 组件间事件通信 |
| Sass | 样式预处理 |
| ECharts | 统计图表(如用户数据走势) |
| wangEditor | 富文本编辑 |
| xlsx | 列表数据导出 Excel |
| vue3-photo-preview | 图片点击预览 |
| vuedraggable | 拖拽排序 |
| ESLint | 代码规范检查 |
| unplugin-auto-import | 自动导入 Vue API,减少样板 import |
认证内核基于开源框架 Sa-Token(v1.45)搭建 —— 一个 GitHub 18k+ star、经海量项目验证的一站式权限认证框架。前后端均选用社区最新主流版本(Spring Boot 4、Vite 8、Vue Router 5 等),招得到人、改得动码、留得住知识,不会成为团队的技术孤岛。
Delivery六、交付标准与售后
6.1、购买包含权益
您购买的不是一个"黑盒授权",而是一整套可拥有、可掌控、可演进的资产:
- 1、Sa-Max 全套代码永久使用权,技术咨询期内新版本免费更新权。
- 2、Sa-Max 在线开发文档、接口文档地址。
- 3、Sa-Max 项目正版授权 License 码。
- 4、技术咨询服务。按照您选择的「基础咨询 / 高级咨询」档位提供,详见下方 6.2、6.3。
- 5、可选择是否开票。
6.2、技术咨询介绍
对 SSO / OAuth2 没经验?担心买了对接不上?先别怕!对商业版用户,我们提供的不仅是代码本身,更是专业的技术咨询支持。
可咨询范围:
- 1、有关 Sa-Max 项目的接入、使用、配置、报错排查、文档范围内使用说明等问题。
- 2、有关 Sa-Max 的架构设计、方案选型、最佳实践等指导建议。
- 3、有关 Sa-Max 在线开发文档、接口文档不理解之处的答疑解惑。
- 4、有关 Sa-Max 的源码设计提问解答、核心设计理念提问解答。
不可咨询范围(服务边界):
- 1、只回答 Sa-Max 项目相关问题,不回答与项目无关的问题。
- 2、不提供帮写代码服务。
- 3、只提供快问快答类技术咨询回复,不提供论文式咨询回复。(何为论文式技术咨询?如:@我方技术人员 这是我们的项目需求书,请帮助我们出一份权限架构设计文档 —— 此类问题需要耗费大量时间与精力,我们无法提供回复。)
- 4、针对同一技术问题翻来覆去的多次提问,我们后期可能会拒绝再次回复。
- 5、部分功能需求可能超出我们的技术能力范围,我们无法提供有效回复建议。
- 6、如您对咨询范围有其它疑问,可在下单前添加 sa-token 小助手,进行咨询确认。
6.3、技术咨询等级介绍
我们提供两种咨询等级:[ 基础咨询 ] 和 [ 高级咨询 ] ,这两种等级可咨询范围一致,区别仅在于咨询人数与对接方式的不同。
基础咨询:
由您团队的核心技术负责人专门和我们做技术咨询对接,一对一回复咨询。
高级咨询:
为您的开发团队单独拉起一个群聊,提供项目相关技术咨询回复,最多支持 5 人进群。
若员工离职或其它原因发生人事变动,可申请替换群成员;每1年服务期可获得 12 名成员替换名额。(如购买3年服务可获得36名成员替换名额)
参考图:
更多有关技术咨询介绍,请参考:https://sa-max.cn/index-sspx.html
Our Team七、团队介绍
Sa-Token 开发团队自 2019 年组建,深耕登录鉴权 / 统一认证架构设计多年。代表作开源项目 Sa-Token(一站式 Java 权限认证框架)广受开发者认可,斩获多项荣誉证书与奖杯。
7.1、荣誉证书墙
点击证书图片可放大查看。












7.2、已服务 1000+ 付费主体
目前已有 1000+ 主体(个人 / 民企 / 知名国企 / 在澳企业 / 政府办公室 / 事业单位 / 顶尖科研机构 / 知名高校)选择 Sa-Token 的付费产品:
涉客户信息数据,白皮书内不便展示,具体可参考:https://sa-max.cn/index.html#index-paid-clients-heading
Contact Us八、联系我们
全源码交付,快速集成。一次购买,永久授权,省去数月(乃至数年)的自研成本。让统一认证的交付成本降低 90% 以上。
微信扫一扫,添加 [ sa-token 小助手 ],把您的业务场景告诉我们,可为您免费做一次 "是否合适采用 Sa-Max 对接" 的评估。
© Sa-Token 开发团队 · Sa-Max 产品白皮书 · 本文档功能描述以实际交付源码与在线演示为准