1. Sa-Token 介绍
Sa-Token 是一个轻量级 Java 权限认证框架,主要解决:登录认证、权限认证、单点登录、OAuth2.0、分布式Session会话、微服务网关鉴权 等一系列权限相关问题。
功能结构图
2. 登录认证
对于一些登录之后才能访问的接口(例如:查询我的账号资料),我们通常的做法是增加一层接口校验:
-
如果校验通过,则:正常返回数据。
-
如果校验未通过,则:抛出异常,告知其需要先进行登录。
那么,判断会话是否登录的依据是什么?我们先来简单分析一下登录访问流程:
-
用户提交 name + password 参数,调用登录接口。
-
登录成功,返回这个用户的 Token 会话凭证。
-
用户后续的每次请求,都携带上这个 Token。
-
服务器根据 Token 判断此会话是否登录成功。
所谓登录认证,指的就是服务器校验账号密码,为用户颁发 Token 会话凭证的过程,这个Token 也是我们后续判断会话是否登录的关键所在。
2.1 登录与注销
// 会话登录:参数填写要登录的账号id,建议的数据类型:long | int | String, 不可以传入复杂类型,如:User、Admin 等等
StpUtil.login(Object id);
只此一句代码,便可以使会话登录成功,实际上,Sa-Token 在背后做了大量的工作,包括但不限于:
-
检查此账号是否之前已有登录
-
为账号生成 Token 凭证与 Session 会话
-
通知全局侦听器,xx 账号登录成功
-
将 Token 注入到请求上下文
-
等等其它工作……
只需要记住关键一点:Sa-Token 为这个账号创建了一个Token凭证,且通过 Cookie 上下文返回给了前端。
此处仅仅做了会话登录,但并没有主动向前端返回 Token 信息。严格来讲是需要的,只不过 StpUtil.login(id) 方法利用了 Cookie 自动注入的特性,省略了你手写返回 Token 的代码。
// 当前会话注销登录
StpUtil.logout();
// 获取当前会话是否已经登录,返回true=已登录,false=未登录
StpUtil.isLogin();
// 检验当前会话是否已经登录, 如果未登录,则抛出异常:`NotLoginException`
StpUtil.checkLogin();
2.2 会话查询
// 获取当前会话账号id, 如果未登录,则抛出异常:`NotLoginException`
StpUtil.getLoginId();
// 类似查询API还有:
StpUtil.getLoginIdAsString(); // 获取当前会话账号id, 并转化为`String`类型
StpUtil.getLoginIdAsInt(); // 获取当前会话账号id, 并转化为`int`类型
StpUtil.getLoginIdAsLong(); // 获取当前会话账号id, 并转化为`long`类型
// ---------- 指定未登录情形下返回的默认值 ----------
// 获取当前会话账号id, 如果未登录,则返回null
StpUtil.getLoginIdDefaultNull();
// 获取当前会话账号id, 如果未登录,则返回默认值 (`defaultValue`可以为任意类型)
StpUtil.getLoginId(T defaultValue);
2.3 Token 查询
// 获取当前会话的token值
StpUtil.getTokenValue();
// 获取当前`StpLogic`的token名称
StpUtil.getTokenName();
// 获取指定token对应的账号id,如果未登录,则返回 null
StpUtil.getLoginIdByToken(String tokenValue);
// 获取当前会话剩余有效期(单位:s,返回-1代表永久有效)
StpUtil.getTokenTimeout();
// 获取当前会话的token信息参数
StpUtil.getTokenInfo();
3. 权限认证
所谓权限认证,核心逻辑就是判断一个账号是否拥有指定权限:
-
有,就让你通过。
-
没有?那么禁止访问!
深入到底层数据中,就是每个账号都会拥有一个权限码集合,框架来校验这个集合中是否包含指定的权限码。
例如:当前账号拥有权限码集合 ["user-add", "user-delete", "user-get"]
,这时候我来校验权限 "user-update",则其结果就是:验证失败,禁止访问。
3.1 获取当前账号权限码集合
因为每个项目的需求不同,其权限设计也千变万化,因此 [ 获取当前账号权限码集合 ]
这一操作不可能内置到框架中, 所以 Sa-Token 将此操作以接口的方式暴露给你,以方便你根据自己的业务逻辑进行重写。
你需要做的就是新建一个类,实现 StpInterface接口,例如以下代码:
/**
* 自定义权限验证接口扩展
*/
@Component // 保证此类被SpringBoot扫描,完成Sa-Token的自定义权限验证扩展
public class StpInterfaceImpl implements StpInterface {
/**
* 返回一个账号所拥有的权限码集合
*/
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
// 本list仅做模拟,实际项目中要根据具体业务逻辑来查询权限
List<String> list = new ArrayList<String>();
list.add("101");
list.add("user.add");
list.add("user.update");
list.add("user.get");
// list.add("user.delete");
list.add("art.*");
return list;
}
/**
* 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
*/
@Override
public List<String> getRoleList(Object loginId, String loginType) {
// 本list仅做模拟,实际项目中要根据具体业务逻辑来查询角色
List<String> list = new ArrayList<String>();
list.add("admin");
list.add("super-admin");
return list;
}
}
参数解释:
-
loginId: 账号id,即你在调用
StpUtil.login(id)
时写入的标识值。 -
loginType: 账号体系标识,此处暂时忽略,可以详细了解
[ 多账户认证 ]
3.2 权限校验
然后就可以用以下api来鉴权了
// 获取:当前账号所拥有的权限集合
StpUtil.getPermissionList();
// 判断:当前账号是否含有指定权限, 返回 true 或 false
StpUtil.hasPermission("user.add");
// 校验:当前账号是否含有指定权限, 如果验证未通过,则抛出异常: NotPermissionException
StpUtil.checkPermission("user.add");
// 校验:当前账号是否含有指定权限 [指定多个,必须全部验证通过]
StpUtil.checkPermissionAnd("user.add", "user.delete", "user.get");
// 校验:当前账号是否含有指定权限 [指定多个,只要其一验证通过即可]
StpUtil.checkPermissionOr("user.add", "user.delete", "user.get");
3.3 角色校验
在Sa-Token中,角色和权限可以独立验证
// 获取:当前账号所拥有的角色集合
StpUtil.getRoleList();
// 判断:当前账号是否拥有指定角色, 返回 true 或 false
StpUtil.hasRole("super-admin");
// 校验:当前账号是否含有指定角色标识, 如果验证未通过,则抛出异常: NotRoleException
StpUtil.checkRole("super-admin");
// 校验:当前账号是否含有指定角色标识 [指定多个,必须全部验证通过]
StpUtil.checkRoleAnd("super-admin", "shop-admin");
// 校验:当前账号是否含有指定角色标识 [指定多个,只要其一验证通过即可]
StpUtil.checkRoleOr("super-admin", "shop-admin");
权限通配符
Sa-Token允许你根据通配符指定泛权限,例如当一个账号拥有art.*
的权限时,art.add
、art.delete
、art.update
都将匹配通过
上帝权限:当一个账号拥有 "*
" 权限时,他可以验证通过任何权限码 (角色认证同理)
前端有了鉴权后端还需要鉴权吗?
需要!
前端的鉴权只是一个辅助功能,对于专业人员这些限制都是可以轻松绕过的,为保证服务器安全,无论前端是否进行了权限校验,后端接口都需要对会话请求再次进行权限校验!
4. 前后台分离(无Cookie模式)
1.何为无 Cookie 模式?
无 Cookie 模式:特指不支持 Cookie 功能的终端,通俗来讲就是我们常说的 —— 前后台分离模式。
后端将 token 返回到前端
首先调用 StpUtil.login(id)
进行登录。
调用 StpUtil.getTokenInfo()
返回当前会话的 token 详细参数。
-
此方法返回一个对象,其有两个关键属性:
tokenName
和tokenValue
(token 的名称和 token 的值)。 -
将此对象传递到前台,让前端人员将这两个值保存到本地。
2.前端将 token 提交到后端
无论是app还是小程序,其传递方式都大同小异。
那就是,将 token 塞到请求header里 ,格式为:{tokenName: tokenValue}
。
3.只要按照如此方法将token值传递到后端,Sa-Token 就能像传统PC端一样自动读取到 token 值,进行鉴权。
4.你可能会有疑问,难道我每个ajax都要写这么一坨?岂不是麻烦死了?
你当然不能每个 ajax 都写这么一坨,因为这种重复性代码都是要封装在一个函数里统一调用的。
5. Sa-Token 集成 Redis
Sa-Token 默认将数据保存在内存中,此模式读写速度最快,且避免了序列化与反序列化带来的性能消耗,但是此模式也有一些缺点,比如:
-
重启后数据会丢失。
-
无法在分布式环境中共享数据。
为此,Sa-Token 提供了扩展接口,你可以轻松将会话数据存储在 Redis、Memcached等专业的缓存中间件中, 做到重启数据不丢失,而且保证分布式环境下多节点的会话一致性。
以下是官方提供的 Redis 集成包:
<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-dao-redis-jackson</artifactId>
<version>1.34.0</version>
</dependency>
集成 Redis 请注意:
1.无论使用哪种序列化方式,你都必须为项目提供一个 Redis 实例化方案,例如:
<!-- 提供Redis连接池 -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency>
2.配置Redis 连接信息
spring:
# redis配置
redis:
# Redis数据库索引(默认为0)
database: 0
# Redis服务器地址
host: 127.0.0.1
# Redis服务器连接端口
port: 6379
# Redis服务器连接密码(默认为空)
# password:
# 连接超时时间
timeout: 10s
lettuce:
pool:
# 连接池最大连接数
max-active: 200
# 连接池最大阻塞等待时间(使用负值表示没有限制)
max-wait: -1ms
# 连接池中的最大空闲连接
max-idle: 10
# 连接池中的最小空闲连接
min-idle: 0
3.集成 Redis 后,是我额外手动保存数据,还是框架自动保存?
框架自动保存。集成 Redis 只需要引入对应的 pom依赖 即可,框架所有上层 API 保持不变。
4.集成包版本问题
Sa-Token-Redis
集成包的版本尽量与 Sa-Token-Starter
集成包的版本一致,否则可能出现兼容性问题。
6. SpringBoot 集成 Sa-Token
以最新版本 1.34.0为例
6.1 创建项目
在 IDE 中新建一个 SpringBoot 项目,例如:sa-token-demo-springboot
6.2 添加依赖
在项目中添加依赖
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Sa-Token 权限认证,在线文档:https://sa-token.cc -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</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>
<!-- 提供Redis连接池 -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
6.3 设置配置文件
server:
# 端口
port: 8081
############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
sa-token:
# token名称 (同时也是cookie名称)
token-name: satoken
# token有效期,单位s 默认30天, -1代表永不过期
timeout: 2592000
# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
activity-timeout: -1
# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录)
is-concurrent: true
# 在多人登录同一账号时,是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token)
is-share: true
# token风格
token-style: uuid
# 是否输出操作日志
is-log: false
spring:
# redis配置
redis:
# Redis数据库索引(默认为0)
database: 0
# Redis服务器地址
host: 127.0.0.1
# Redis服务器连接端口
port: 6379
# Redis服务器连接密码(默认为空)
password: abc123
# 连接超时时间
timeout: 10s
lettuce:
pool:
# 连接池最大连接数
max-active: 200
# 连接池最大阻塞等待时间(使用负值表示没有限制)
max-wait: -1ms
# 连接池中的最大空闲连接
max-idle: 10
# 连接池中的最小空闲连接
min-idle: 0
6.4 创建启动类
@SpringBootApplication
public class SaTokenDemoApplication {
public static void main(String[] args) throws JsonProcessingException {
SpringApplication.run(SaTokenDemoApplication.class, args);
System.out.println("启动成功:Sa-Token配置如下:" + SaManager.getConfig());
}
}
6.5 定义用户信息类
@Data
@Accessors(chain = true)
@AllArgsConstructor
public class UserInfo {
private Long userId;
private String name;
private String email;
}
6.6 自定义权限验证接口扩展
@Component // 保证此类被SpringBoot扫描,完成Sa-Token的自定义权限验证扩展
public class StpInterfaceImpl implements StpInterface {
/**
* 返回一个账号所拥有的权限码集合
*/
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
// 本list仅做模拟,实际项目中要根据具体业务逻辑来查询权限
// List<String> list = new ArrayList<String>();
// list.add("user.add");
// list.add("user.get");
// list.add("user.delete");
// list.add("art.*");
//从redis中获取权限
List<String> authList = (List<String>) StpUtil.getSession().get("authList");
return authList;
}
/**
* 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
* @param loginId 账号id,即你在调用 StpUtil.login(id) 时写入的标识值
* @param loginType 账号体系标识
* @author: yh
* @date: 2023/2/12
*/
@Override
public List<String> getRoleList(Object loginId, String loginType) {
// 本list仅做模拟,实际项目中要根据具体业务逻辑来查询角色
List<String> list = new ArrayList<String>();
list.add("admin");
list.add("super-admin");
return list;
}
}
6.7 创建测试Controller
@RestController
@RequestMapping("/user")
public class UserController {
/**
* 测试登录,浏览器访问: http://localhost:8081/user/doLogin?username=zhang&password=123456
*/
@RequestMapping("/doLogin")
public SaResult doLogin(String username, String password) {
// 此处仅作模拟示例,真实项目需要从数据库中查询数据进行比对
if("zhang".equals(username) && "123456".equals(password)) {
// 第1步,先登录上
StpUtil.login(10001);
}
//第2步,加载用户信息和权限信息
StpUtil.getSession().set("loginInfo", new UserInfo(10001L, "张三", "123123@163.com"));
//加载权限,只给user.add的权限
List<String> authList = new ArrayList<String>();
authList.add("user.add");
StpUtil.getSession().set("authList", authList);
// 第3步,获取 Token 相关参数
SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
// 第4步,返回给前端
return SaResult.data(tokenInfo);
}
/**
* 查询登录状态
*/
@RequestMapping("/isLogin")
public String isLogin() {
return "当前会话是否登录:" + StpUtil.isLogin();
}
/**
* 获取用户信息
*/
@RequestMapping("/getUserInfo")
public UserInfo getUserInfo() {
UserInfo loginInfo = (UserInfo) StpUtil.getSession().get("loginInfo");
return loginInfo;
}
/**
* 测试方法校验权限
*/
@GetMapping(value = "/add")
public String add(){
StpUtil.checkPermission("user.add");
return "ok";
}
@GetMapping(value = "/update")
public String update(){
StpUtil.checkPermission("user.update");
return "ok";
}
}
6.8 运行
启动项目,Copy Configuration
再启动一个实例,这时候我们就同时启动了两个实例
这样就可以测试出在集群部署情况下登录信息会不会有问题,然后用接口测试工具依次访问上述测试接口
1、 登录
http://localhost:8081/user/doLogin?username=zhang&password=123456
此时查看redis中数据,可以看到登录信息和权限都保存在redis中了
2、 查询登录状态
http://localhost:8081/user/isLogin
注意header里没有cookie
把登录接口返回的tokenName和tokenValue加入到请求header中
只有请求携带对应的token,登录状态才为:true
3、 获取用户信息
这里调用端口为8082的实例
http://localhost:8082/user/getUserInfo
4、 调用添加用户接口
测试是否有添加接口权限,登录的时候我们赋予了添加用户的权限
http://localhost:8082/user/add
5、 调用更新用接口
测试是否有更新用户接口权限,登录的时候我们没有赋予更新用户的权限
http://localhost:8082/user/update
结果可以看到没有更新用户接口的权限。