Sa-Token 单点登录第一篇：搭建 SSO-Server 统一认证中心

大家好，由于单篇博客长度有限，我将针对 SSO 单点登录 开启一个系列文章，此为第一篇，想完整的了解 SSO 技术的欢迎点开我的账号动态参考本系列其它文章。

Sa-Token 是一个轻量级 java 权限认证框架，主要解决登录认证、权限认证、单点登录、OAuth2、微服务网关鉴权 等一系列权限相关问题。
Gitee 开源地址：https://gitee.com/dromara/sa-token

凡是稍微上点规模的系统，统一认证中心都是绕不过去的槛。而单点登录 —— 便是我们搭建统一认证中心的关键。

本篇将介绍如何使用 Sa-Token 方便的搭建一个 sso-server 认证中心。

一、什么是单点登录？解决什么问题？

举个场景，假设我们的系统被切割为N个部分：商城、论坛、直播、社交…… 如果用户每访问一个模块都要登录一次，那么用户将会疯掉，
为了优化用户体验，我们急需一套机制将这N个系统的认证授权互通共享，让用户在一个系统登录之后，便可以畅通无阻的访问其它所有系统。

单点登录——就是为了解决这个问题而生！

简而言之，单点登录可以做到：在多个互相信任的系统中，用户只需登录一次，就可以访问所有系统。

二、架构选型

Sa-Token-SSO 由简入难划分为三种模式，解决不同架构下的 SSO 接入问题：

系统架构	采用模式	简介
前端同域 + 后端同 Redis	模式一	共享 Cookie 同步会话
前端不同域 + 后端同 Redis	模式二	URL重定向传播会话
前端不同域 + 后端不同 Redis	模式三	Http请求获取会话

1. 前端同域：就是指多个系统可以部署在同一个主域名之下，比如：c1.domain.com、c2.domain.com、c3.domain.com。
2. 后端同Redis：就是指多个系统可以连接同一个Redis。PS：这里并不需要把所有项目的数据都放在同一个Redis中，Sa-Token提供了 [权限缓存与业务缓存分离] 的解决方案。
3. 如果既无法做到前端同域，也无法做到后端同Redis，那么只能走模式三，Http请求获取会话（Sa-Token对SSO提供了完整的封装，你只需要按照示例从文档上复制几段代码便可以轻松集成）。

三、Sa-Token-SSO 特性

1. API 简单易用，文档介绍详细，且提供直接可用的集成示例。
2. 支持三种模式，不论是否跨域、是否共享Redis、是否前后端分离，都可以完美解决。
3. 安全性高：内置域名校验、Ticket校验、秘钥校验等，杜绝Ticket劫持、Token窃取等常见攻击手段（文档讲述攻击原理和防御手段）。
4. 不丢参数：笔者曾试验多个单点登录框架，均有参数丢失的情况，比如重定向之前是：http://a.com?id=1&name=2，登录成功之后就变成了：http://a.com?id=1，Sa-Token-SSO内有专门的算法保证了参数不丢失，登录成功之后原路返回页面。
5. 无缝集成：由于Sa-Token本身就是一个权限认证框架，因此你可以只用一个框架同时解决权限认证 + 单点登录问题，让你不再到处搜索：xxx单点登录与xxx权限认证如何整合……
6. 高可定制：Sa-Token-SSO模块对代码架构侵入性极低，结合Sa-Token本身的路由拦截特性，你可以非常轻松的定制化开发。

在开始SSO三种模式的对接之前，我们必须先搭建一个 SSO-Server 认证中心

四、添加依赖

创建 SpringBoot 项目 sa-token-demo-sso-server，引入依赖：

<!-- Sa-Token 权限认证，在线文档：https://sa-token.com -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.34.0</version>
</dependency>

<!-- Sa-Token 插件：整合SSO -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-sso</artifactId>
    <version>1.34.0</version>
</dependency>

<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-dao-redis-jackson</artifactId>
    <version>1.34.0</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-pool2</artifactId>
</dependency>

<!-- 视图引擎（在前后端不分离模式下提供视图支持） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

<!-- Http请求工具（在模式三的单点注销功能下用到，如不需要可以注释掉） -->
<dependency>
    <groupId>com.dtflys.forest</groupId>
    <artifactId>forest-spring-boot-starter</artifactId>
    <version>1.5.26</version>
</dependency>
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

除了 sa-token-spring-boot-starter 和 sa-token-sso 以外，其它包都是可选的：
- 在 SSO 模式三时 Redis 相关包是可选的
- 在前后端分离模式下可以删除 thymeleaf 相关包
- 在不需要 SSO 模式三单点注销的情况下可以删除 http 工具包

建议先完整测试三种模式之后再对pom依赖进行酌情删减。

五、开放认证接口

新建 SsoServerController，用于对外开放接口：

/**
 * Sa-Token-SSO Server端 Controller 
 */
@RestController
public class SsoServerController {

    /*
     * SSO-Server端：处理所有SSO相关请求 (下面的章节我们会详细列出开放的接口) 
     */
    @RequestMapping("/sso/*")
    public Object ssoRequest() {
        return SaSsoProcessor.instance.serverDister();
    }

    /**
     * 配置SSO相关参数 
     */
    @Autowired
    private void configSso(SaSsoConfig sso) {
        // 配置：未登录时返回的View 
        sso.setNotLoginView(() -> {
            String msg = "当前会话在SSO-Server端尚未登录，请先访问"
                    + "<a href='/sso/doLogin?name=sa&pwd=123456' target='_blank'> doLogin登录 </a>"
                    + "进行登录之后，刷新页面开始授权";
            return msg;
        });

        // 配置：登录处理函数 
        sso.setDoLoginHandle((name, pwd) -> {
            // 此处仅做模拟登录，真实环境应该查询数据进行登录 
            if("sa".equals(name) && "123456".equals(pwd)) {
                StpUtil.login(10001);
                return SaResult.ok("登录成功！").setData(StpUtil.getTokenValue());
            }
            return SaResult.error("登录失败！");
        });

        // 配置 Http 请求处理器 （在模式三的单点注销功能下用到，如不需要可以注释掉） 
        sso.setSendHttp(url -> {
            try {
                // 发起 http 请求 
                System.out.println("------ 发起请求：" + url);
                return Forest.get(url).executeAsString();
            } catch (Exception e) {
                e.printStackTrace();
                return null;
            }
        });
    }

}
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

注意：
- 在setDoLoginHandle函数里如果要获取name, pwd以外的参数，可通过SaHolder.getRequest().getParam("xxx")来获取
- 在 setSendHttp 函数中，使用 try-catch 是为了提高整个注销流程的容错性，避免在一些极端情况下注销失败（例如：某个 Client 端上线之后又下线，导致 http 请求无法调用成功，从而阻断了整个注销流程）

全局异常处理：

@RestControllerAdvice
public class GlobalExceptionHandler {
    // 全局异常拦截 
    @ExceptionHandler
    public SaResult handlerException(Exception e) {
        e.printStackTrace(); 
        return SaResult.error(e.getMessage());
    }
}
1
2
3
4
5
6
7
8
9

六、application.yml配置

# 端口
server:
    port: 9000

# Sa-Token 配置
sa-token: 
    # ------- SSO-模式一相关配置  (非模式一不需要配置) 
    # cookie: 
        # 配置 Cookie 作用域 
        # domain: stp.com 

    # ------- SSO-模式二相关配置 
    sso: 
        # Ticket有效期 (单位: 秒)，默认五分钟 
        ticket-timeout: 300
        # 所有允许的授权回调地址
        allow-url: "*"
        # 是否打开单点注销功能
        is-slo: true

        # ------- SSO-模式三相关配置 （下面的配置在SSO模式三并且 is-slo=true 时打开）
        # 是否打开模式三 
        isHttp: true
        # 接口调用秘钥（用于SSO模式三的单点注销功能）
        secretkey: kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
        # ---- 除了以上配置项，你还需要为 Sa-Token 配置http请求处理器（文档有步骤说明） 

spring: 
    # Redis配置 （SSO模式一和模式二使用Redis来同步会话）
    redis:
        # Redis数据库索引（默认为0）
        database: 1
        # Redis服务器地址
        host: 127.0.0.1
        # Redis服务器连接端口
        port: 6379
        # Redis服务器连接密码（默认为空）
        password: 

forest: 
    # 关闭 forest 请求日志打印
    log-enabled: false
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

注意点：sa-token.sso.allow-url为了方便测试配置为*，线上生产环境一定要配置为详细URL地址 （之后的章节我们会详细阐述此配置项）

七、创建启动类

@SpringBootApplication
public class SaSsoServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SaSsoServerApplication.class, args);
        System.out.println("\n------ Sa-Token-SSO 认证中心启动成功");
    }
}
1
2
3
4
5
6
7

启动项目，不出意外的情况下我们将看到如下输出：

访问统一授权地址：

http://localhost:9000/sso/auth

可以看到这个页面目前非常简陋，这是因为我们以上的代码示例，主要目标是为了带大家从零搭建一个可用的SSO认证服务端，所以就对一些不太必要的步骤做了简化。

大家可以下载运行一下 Sa-Token 官方仓库里的示例/sa-token-demo/sa-token-demo-sso-server/，里面有制作好的登录页面：

默认账号密码为：sa / 123456，先别着急点击登录，因为我们还没有搭建对应的 Client 端项目，
真实项目中我们是不会直接从浏览器访问 /sso/auth 授权地址的，我们需要在 Client 端点击登录按钮重定向而来。

---

现在我们先来看看除了 /sso/auth 统一授权地址，这个 SSO-Server 认证中心还开放了哪些API：

八、SSO-Server 认证中心开放接口参考

如果你的 SSO-Server 端和 SSO-Client 端都使用 Sa-Token-SSO 搭建，那么你可以忽略以下部分内容，直接使用 Sa-Token SSO 模块进行对接。

如果你仅在 SSO-Server 端使用 Sa-Token-SSO 搭建，而 SSO-Client 端使用其它框架的话，那么你就需要手动调用 http 请求来对接 SSO-Server 认证中心，
下面的 API 列表将给你的对接步骤做一份参考。

1、单点登录授权地址

http://{host}:{port}/sso/auth
1

接收参数：

参数	是否必填	说明
redirect	是	登录成功后的重定向地址，一般填写 location.href（从哪来回哪去）
mode	否	授权模式，取值 [simple, ticket]，simple=登录后直接重定向，ticket=带着ticket参数重定向，默认值为ticket

访问接口后有两种情况：
- 情况一：当前会话在 SSO 认证中心未登录，会进入登录页开始登录。
- 情况二：当前会话在 SSO 认证中心已登录，会被重定向至 redirect 地址，并携带 ticket 参数。

2、RestAPI 登录接口

http://{host}:{port}/sso/doLogin
1

接收参数：

参数	是否必填	说明
name	是	用户名
pwd	是	密码

此接口属于 RestAPI (使用ajax访问)，会进入后端配置的 sso.setDoLoginHandle 函数中，此函数的返回值即是此接口的响应值。

另外需要注意：此接口并非只能携带 name、pwd 参数，因为你可以在方法里通过 SaHolder.getRequest().getParam("xxx") 来获取前端提交的其它参数。

3、Ticket 校验接口

此接口仅配置模式三 (isHttp=true) 时打开

http://{host}:{port}/sso/checkTicket
1

接收参数：

参数	是否必填	说明
ticket	是	在步骤 1 中授权重定向时的 ticket 参数
ssoLogoutCall	否	单点注销时的回调通知地址，只在SSO模式三单点注销时需要携带此参数

返回值场景：
- 校验成功时：

{
    "code": 200,
    "msg": "ok",
    "data": "10001" // 此 ticket 指向的 loginId
}
1
2
3
4
5

• 校验失败时：

{
    "code": 500,
    "msg": "无效ticket：vESj0MtqrtSoucz4DDHJnsqU3u7AKFzbj0KH57EfJvuhkX1uAH23DuNrMYSjTnEq",
    "data": null
}
1
2
3
4
5

4、单点注销接口

http://{host}:{port}/sso/signout
1

此接口有两种调用方式

4.1、方式一：在 Client 的前端页面引导用户直接跳转，并带有 back 参数

例如：

http://{host}:{port}/sso/signout?back=xxx
1

用户注销成功后将返回 back 地址

4.2、方式二：在 Client 的后端通过 http 工具来调用

接受参数：

参数	是否必填	说明
loginId	是	要注销的账号 id
timestamp	是	当前时间戳，13位
nonce	是	随机字符串
sign	是	签名，生成算法：md5( loginId={账号id}&nonce={随机字符串}&timestamp={13位时间戳}&key={secretkey秘钥} )

例如：

http://{host}:{port}/sso/signout?loginId={value}&timestamp={value}&nonce={value}&sign={value}
1

将返回 json 数据结果，形如：

{
    "code": 200,    // 200表示请求成功，非200标识请求失败
    "msg": "单点注销成功",
    "data": null
}
1
2
3
4
5

如果单点注销失败，将返回：

{
    "code": 500,    // 200表示请求成功，非200标识请求失败
    "msg": "签名无效：xxx",  // 失败原因 
    "data": null
}
1
2
3
4
5

SSO 认证中心只有这四个接口，此部分内容先介绍至此，接下来的文章我会依次介绍在 Sa-Token SSO 中：
同域、跨域、同Redis、跨Redis、前后端分离、前后端一体等各种不同架构下的单点登录对接流程。

---

参考资料

• Sa-Token 文档：https://sa-token.com
• Gitee 仓库地址：https://gitee.com/dromara/sa-token
• GitHub 仓库地址：https://github.com/dromara/sa-token