sa-token SSO 单点登录三种模式完整实战

Wed, 15 Dec 2021 00:00:00 +0800

sa-token 是国内 Dromara 组织下的轻量级 Java 权限认证框架，2021 年 GitHub star 数超过 8k。sa-token 的 SSO 模块是国内最简洁的 Java 单点登录方案之一——它把 SSO 抽象成三种"客户端-服务端"模式，让不同业务场景都能找到合适方案。本文基于 sa-token 1.44.0 版本做一次完整实战。

本文写于 2021 年 12 月——sa-token SSO 模块稳定迭代后的版本。

一、SSO 接口规范

sa-token 定义了一套标准的 SSO RESTful 接口规范，所有模式都遵循这套接口：

1.1 服务端（SSO-Server）接口

端	接口	解释
server	`/sso/auth`	单点登录授权（重定向到登录页）
server	`/sso/doLogin`	restapi 登录接口（自定义 `doLoginHandle`）
server	`/sso/signout`	单点登录注销
server	`/sso/pusS`	消息推送（模式三服务端推送）
server	`/sso/userinfo`	获取用户信息（自定义）

1.2 客户端（SSO-Client）接口

端	接口	解释
client	`/sso/login`	客户端登录地址（重定向到 server）
client	`/sso/logout`	客户端注销
client	`/sso/logoutCall`	单点注销回调
client	`/sso/pusC`	消息推送（模式三客户端接收）
client	`/sso/myInfo`	客户端查询用户信息

特点：

所有接口都是基于 HTTP 的 RESTful
通过 redirect 参数传递回调地址
模式三需要主动 HTTP 推送（基于 Forest HTTP 工具）

二、SSO 模式一：前端同域 + 后端同 Redis

2.1 原理

共享 Cookie 来做到前端 Token 的共享，从而达到后端的 Session 会话共享：

1
2
3
4
5


App1（a.example.com） ──┐
 │ 同域 stp.com 共享 Cookie
App2（a.example.com） ──┤
 │ 同 Redis 共享 Session
App3（a.example.com） ──┘

架构：

所有应用挂在同一个域下（如 stp.com）
登录后 Cookie 写入 stp.com 域
后续访问任何应用都自动带上 Cookie
Session 存储在同一个 Redis

2.2 优点

最简单：零额外开发
最稳定：基于 Cookie + Redis 标准方案
最高性能：无重定向，无额外 HTTP 请求

2.3 缺点

必须同域：所有应用必须挂在同一个父域下
不能跨域：如果是不同根域的多个产品线，不能用此模式

2.4 适用场景

同公司多个子系统（如 crm.stp.com、erp.stp.com、oa.stp.com）
微服务架构内部系统

三、SSO 模式二：前端不同域 + 后端同 Redis

3.1 原理

采用 URL 重定向，以 ticket 码为授权中介，做到多个系统间的会话传播：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


App1（a.com） App2（b.com）
 │ │
 │ ① /sso/auth?redirect= │
 ▼ │
SSO-Server（sso.com） │
 │ │
 │ ② 重定向到 /sso/login │
 ▼ │
登录页（sso.com） │
 │ │
 │ ③ 提交账密 │
 ▼ │
SSO-Server │
 │ │
 │ ④ 颁发 ticket + 重定向 │
 │ /sso/login?ticket=xxx│
 ▼ │
 ┌─────────────────────────▶│
 │ ▼
 │ App2 回调 /sso/login?ticket
 │ │
 │ ▼
 │ 携带 ticket 调用 SSO-Server /sso/authTicket
 │ │
 │ ▼
 │ SSO-Server 校验 ticket
 │ │
 │ ▼
 │ 返回 App2 的 token，写入 App2 的 Session

关键流程：

用户访问 App1（a.com）
App1 发现自己未登录，重定向到 SSO-Server /sso/auth?redirect=...
SSO-Server 发现自己未登录，返回登录页
用户登录成功，SSO-Server 生成 ticket 写入 Redis
SSO-Server 重定向回 App1 redirect 地址，带上 ticket
App1 拿到 ticket，调用 SSO-Server /sso/authTicket 换 App1 的 token
App1 把 token 写入自己的 Session
用户访问 App2（b.com），重复同样流程，但 SSO-Server 已经认识这个用户，自动颁发 ticket（无需再登录）

3.2 优点

支持跨域：不同根域的应用可以登录
基于 ticket：标准 OAuth 2.0 风格
无状态：ticket 一次有效，换完即失效

3.3 缺点

有重定向：首次访问慢一点
配置复杂：需要给每个应用配置 client 名称 + 回调地址

3.4 适用场景

不同子公司的多个产品（如 aliyun.com、dingtalk.com、alipay.com）
企业 SaaS 多租户

四、SSO 模式三：前端不同域 + 后端不同 Redis

4.1 原理

采用 Http 请求主动查询会话，做到 Client 端与 Server 端的会话同步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


App1（a.com） App2（b.com）
 │ │
 │ │ ① /sso/login?redirect=...
 │ ▼
 │ SSO-Server（sso.com）
 │ │
 │ │ ② ticket=xxx
 │ ▼
 │ App2 调用 /sso/authTicket 换 token
 │ │
 │ ▼
 │ SSO-Server 主动 HTTP 推送
 │ │ /sso/pusC
 │ ▼
 │ App1 也收到推送（同步登录状态）
 │
 │ ③ 收到推送，已登录
 ▼
 全员同步

关键流程：

App2 主动调用 SSO-Server 的 /sso/authTicket 验证 ticket
SSO-Server 验证通过后，主动通过 HTTP POST 推送消息到所有已注册的客户端
所有 App（包括 App1、App2、App3）都收到推送
所有 App 同步更新本地 Session

4.2 优点

真正的分布式：不需要共享 Session
实时同步：注销、踢人、状态变更实时通知
可扩展：App1/2/3/4 任意上下线不影响

4.3 缺点

需要 HTTP 推送：依赖 Forest HTTP 客户端
推送失败容错：推送失败时需要心跳轮询兜底

4.4 适用场景

跨数据中心部署（各应用在不同地域的 Redis）
超大规模 SSO（上百个应用）

五、服务端（SSO-Server）实战

5.1 依赖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


<!-- SpringBoot -->
<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>2.5.14</version>
</parent>

<properties>
 <sa-token.version>1.44.0</sa-token.version>
</properties>

<dependencies>
 <!-- SpringBoot Web -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>

 <!-- Sa-Token 核心 -->
 <dependency>
 <groupId>cn.dev33</groupId>
 <artifactId>sa-token-spring-boot-starter</artifactId>
 <version>${sa-token.version}</version>
 </dependency>

 <!-- Sa-Token SSO 插件 -->
 <dependency>
 <groupId>cn.dev33</groupId>
 <artifactId>sa-token-sso</artifactId>
 <version>${sa-token.version}</version>
 </dependency>

 <!-- Sa-Token Redis 集成 -->
 <dependency>
 <groupId>cn.dev33</groupId>
 <artifactId>sa-token-redis-template</artifactId>
 <version>${sa-token.version}</version>
 </dependency>
 <dependency>
 <groupId>org.apache.commons</groupId>
 <artifactId>commons-pool2</artifactId>
 </dependency>

 <!-- Thymeleaf（前后端不分离模式） -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-thymeleaf</artifactId>
 </dependency>

 <!-- Forest HTTP 客户端（模式三需要） -->
 <dependency>
 <groupId>cn.dev33</groupId>
 <artifactId>sa-token-forest</artifactId>
 <version>${sa-token.version}</version>
 </dependency>
</dependencies>

5.2 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


server:
 port: 9000

# Sa-Token 配置
sa-token:
 is-log: true

 # SSO-Server 配置
 sso-server:
 # Ticket 有效期（单位：秒），默认 5 分钟
 ticket-timeout: 300
 # 主页路由：在 /sso/auth 登录页不指定 redirect 参数时，默认跳转的地址
 home-route: /home
 # 是否启用匿名 client（允许客户端接入时不提交 client 参数）
 allow-anon-client: true
 # 所有允许的授权回调地址（匿名 client 使用）
 allow-url: "*"
 # API 接口调用秘钥（全局默认 + 匿名 client 使用）
 secret-key: kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
 # 应用列表：配置接入的应用信息
 clients:
 # 应用 sso-client1：采用模式一对接（同域、同 Redis）
 sso-client1:
 client: sso-client1
 allow-url: "*"
 # 应用 sso-client2：采用模式二对接（跨域、同 Redis）
 sso-client2:
 client: sso-client2
 allow-url: "*"
 secret-key: SSO-C2-kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
 # 应用 sso-client3：采用模式三对接（跨域、跨 Redis）
 sso-client3:
 client: sso-client3
 allow-url: "*"
 is-push: true
 push-url: http://sa-sso-client1.com:9003/sso/pusC
 secret-key: SSO-C3-kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
 # 应用 sso-client3-resdk：采用 ReSdk 模式对接
 sso-client3-resdk:
 client: sso-client3-resdk
 allow-url: "*"
 is-push: true
 push-url: http://sa-sso-client1.com:9005/sso/pusC
 secret-key: SSO-C3-ReSdk-kQwIOrYvnXmSDkwEiFngrKidMcdrgKor

# Redis 配置
spring:
 redis:
 database: 1
 host: 127.0.0.1
 port: 6379
 password:
 timeout: 10s
 lettuce:
 pool:
 max-active: 200
 max-wait: -1ms
 max-idle: 10
 min-idle: 0

# Forest HTTP 客户端
forest:
 log-enabled: false

5.3 hosts 配置

1
2


# 模拟多域名环境
127.0.0.1 sa-sso-server.com

5.4 测试入口

1

登录页：http://sa-sso-server.com:9000/sso/auth

六、客户端实战

6.1 标准模式客户端

同模式二客户端配置（sso-client2）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


server:
 port: 9002

sa-token:
 sso-client:
 # SSO-Server 域名
 server-url: http://sa-sso-server.com:9000
 # 本应用 Client 标识
 client: sso-client2
 # 本应用密钥（与 Server 端配置一致）
 secret-key: SSO-C2-kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
 # 登录回调地址
 redirect-url: http://sa-sso-client2.com:9002/sso/login

6.2 ReSdk 模式客户端

ReSdk 是 sa-token 提供的一种不依赖 Spring MVC 拦截器的接入方式，适合老项目改造：

1
2
3
4


<dependency>
 <groupId>cn.dev33</groupId>
 <artifactId>sa-token-sso</artifactId>
</dependency>

优点：

业务代码侵入小（只需在 Controller 入口加 1-2 行）
支持非 Spring 项目
支持 GraalVM Native Image

6.3 NoSdk 模式客户端

完全不依赖 Sa-Token，纯 HTTP 调用 SSO 接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<dependencies>
 <!-- SpringBoot Web -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>

 <!-- Forest HTTP 客户端 -->
 <dependency>
 <groupId>com.dtflys.forest</groupId>
 <artifactId>forest-spring-boot-starter</artifactId>
 <version>1.5.26</version>
 </dependency>
</dependencies>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


server:
 port: 9004

forest:
 log-request: true

spring:
 redis:
 database: 2
 host: 127.0.0.1
 port: 6379
 timeout: 10s
 lettuce:
 pool:
 max-active: 200
 max-wait: -1ms
 max-idle: 10
 min-idle: 0

自定义接口：

接口	含义
`/`	client-首页
`/sso/login`	client-登录
`/sso/logout`	client-单点注销
`/sso/logoutCall`	client-单点注销回调
`/sso/myInfo`	client-查询用户信息（sso-server 开放了 `/sso/userinfo` 路由）

hosts：

1
2
3


127.0.0.1 sa-sso-client1
127.0.0.1 sa-sso-client2
127.0.0.1 sa-sso-client3

七、模式选型决策树

graph TD
 A[需要做 SSO] --> B{所有应用是否同域?}
 B -->|是| C[模式一: 同域共享 Cookie]
 B -->|否| D{是否能共享 Redis?}
 D -->|是| E[模式二: 跨域 ticket]
 D -->|否| F[模式三: 跨域跨 Redis 主动查询]

 C --> G{性能要求高?}
 G -->|是| C
 G -->|否| E

 E --> H{需要实时同步?}
 H -->|是| F
 H -->|否| E

八、写在最后

sa-token 的 SSO 模块是国内 Java 单点登录的标杆方案——配置简单、模式丰富、社区活跃。

个人建议：

同公司多子系统：模式一（同域）最快

不同根域多产品线：模式二（跨域 ticket）最经典

跨数据中心部署：模式三（跨域跨 Redis 推送）最稳

老项目改造：ReSdk 模式侵入最小

彻底解耦：NoSdk 模式只走 HTTP

参考资料

九、2024+ 视角：sa-token 1.38+ → 1.44+、OAuth2.0 与 OIDC 完整支持

本文写于 2021 年 12 月（sa-token 1.44.0 时代），sa-token 在 2024-2025 年完成了一次"质变"——从"权限认证"扩展为"OAuth2.0 / OIDC 全家桶"。

9.1 sa-token 版本演进（2021 → 2025）

版本	时间	关键变化
1.30.x	2021-06	基础 SSO 三模式（本文写于 1.44.0 之后，2021-12）
1.34.x	2023-08	新增 OAuth2.0 完整模块（authorization_code / client_credentials / password）
1.36.x	2024-02	新增 OIDC（OpenID Connect）模块，IdP / RP 一应俱全
1.38.x	2024-08	Spring Boot 3.x 完整支持——`sa-token-spring-boot3-starter` 单独发包
1.40.x	2025-03	JDK 21 虚拟线程适配、JWT 增强（jose4j 升级）
1.42.x	2025-08	Sa-Token SSO 三模式升级，新增模式四：SSO-IdP 标准 OIDC 接入
1.44.x	2026-01	前后端分离 OAuth2.0 PKCE 模式、多租户增强（Tenancy 抽象）

关键变化：从 1.36 开始，sa-token 不再只是"权限框架"，而是"OAuth2.0 / OIDC 服务端 + 客户端"——可以拿来做完整 IdP 平台。

9.2 2024+ 新模式：模式四 SSO-IdP（OIDC 标准）

2021 年本文介绍了三种 SSO 模式，2025 年 sa-token 新增"模式四"：

1
2
3
4
5
6
7


 IdP 平台
 │
 ┌───────────────────┼───────────────────┐
 ▼ ▼ ▼
 App1 (OIDC RP) App2 (OIDC RP) App3 (OIDC RP)
 - 企业自研 - 商业 SaaS - 第三方系统
 - 用 sa-token - 用 keycloak - 用 Auth0

特点：

完全兼容 OIDC 规范——任何标准 OIDC 客户端（keycloak / Auth0 / Okta）都能接入
Discovery Endpoint（/.well-known/openid-configuration）自动暴露 IdP 元信息
支持 PKCE——2024+ 移动互联网标配（防止授权码拦截）
JWK 端点（/.well-known/jwks.json）——第三方系统可以本地验证 JWT，无需请求 IdP

适用场景：企业自建 IdP 平台，对外开放给第三方应用或 SaaS 系统。

9.3 OAuth2.0 实战补充（2024+ 主流用法）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# sa-token 1.38+ 配置 OAuth2.0 服务端
sa-token:
 oauth2:
 # 授权码模式 token 有效期
 code-timeout: 300
 # access_token 有效期
 access-token-timeout: 7200
 # refresh_token 有效期
 refresh-token-timeout: 2592000
 # 是否强制 PKCE（2024+ 强烈建议 true）
 force-pkce: true
 # 客户端列表
 clients:
 - client-id: web-admin
 client-secret: kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
 grant-types:
 - authorization_code
 - refresh_token
 scopes:
 - user.read
 - user.write
 redirect-uris:
 - https://admin.example.com/oauth/callback
 - client-id: mobile-app
 # 移动端走 PKCE，不需要 client_secret
 grant-types:
 - authorization_code
 scopes:
 - user.profile
 redirect-uris:
 - com.example.app://oauth/callback
 require-pkce: true

2024+ 主流选择：

Web 后台 → authorization_code + client_secret
移动 App / SPA → authorization_code + PKCE（不再用 implicit 模式）
服务间调用 → client_credentials
老系统对接 → password（已不推荐，2024+ 多数项目禁用）

9.4 与 Spring Authorization Server / Keycloak 的对比

维度	sa-token OAuth2.0	Spring Authorization Server	Keycloak
学习成本	极低（中文文档）	中（需理解 Spring Security 6）	高（独立服务）
部署复杂度	嵌入式	嵌入式	独立进程
OIDC 完整度	1.42+ 完整	完整	完整（业界标杆）
国内合规	强（等保 2.0 SM2/SM4 支持）	中	弱（默认算法不符合国密）
生态丰富度	国内最活跃	国际化	国际化
多租户	1.44+ 增强	中	强
Spring Boot 3.x	1.38+ 完整	1.2+	26+

2024+ 选型经验：

国内中小项目：sa-token（最简单 + 中文社区）

企业级合规（金融/政务）：sa-token + 国密算法扩展

跨云/跨国大厂：Keycloak / Spring Authorization Server

不想自己运维：Auth0 / Authing（国内）/ 阿里云 IDaaS

9.5 个人回顾：从"单点登录"到"全场景身份中台"

3 年前写这篇文章时，sa-token 还只是"轻量级 Java 权限框架"。2024-2026 它已经演变成"Java 身份中台"：

2018-2020：单点登录（SSO）
2020-2022：权限认证 + 微服务网关
2022-2024：OAuth2.0 完整实现
2024-2026：OIDC IdP 平台 + 多租户 + 国密合规

国内 Java 身份认证的"大一统"正在发生——sa-token、Keycloak 都在抢"一站式 IdP"的山头。

如果 2024 年再做 SSO 选型，我会先评估"未来 3 年是否要做 IdP"——是 → sa-token 1.42+ / Keycloak；否 → 单点登录模式二 + 简单 Redis 即可。

单点登录 on Liangweidong's blog