Sa-Token，一款更加轻量的权限认证框架
今天给大家介绍一个轻量级 Java 权限认证框架，我们之前一直采用最多的鉴权框架是OAuth2.0或者SpringSecurity，但是两者的配置都相当复杂，学习成本也非常高，所以我一直在试图寻找更好的解决办法，这几天在搭建权限体系平台的时候，调研到了这一款开源框架，后续我会为大家详细介绍这款框架的详细使用。希望大家多多关注点赞支持！！
官网地址：https://sa-token.cc/
Sa-Token介绍
Sa-Token 是一个轻量级 Java 权限认证框架，主要解决：登录认证、权限认证、单点登录、OAuth2.0、分布式Session会话、微服务网关鉴权 等一系列权限相关问题。
它的简单让你感到惊讶，比如最常见的登录：
// 会话登录，参数填登录人的账号id
StpUtil.login(10001);
就仅仅这一行代码即可搞定，无需实现任何接口，无需创建任何配置文件，只需要这一句静态代码的调用，便可以完成会话登录认证。
Sa-Token功能
- 登录认证 —— 单端登录、多端登录、同端互斥登录、七天内免登录
- 权限认证 —— 权限认证、角色认证、会话二级认证
- Session会话 —— 全端共享Session、单端独享Session、自定义Session
- 踢人下线 —— 根据账号id踢人下线、根据Token值踢人下线
- 账号封禁 —— 登录封禁、按照业务分类封禁、按照处罚阶梯封禁
- 持久层扩展 —— 可集成Redis、Memcached等专业缓存中间件，重启数据不丢失
- 分布式会话 —— 提供jwt集成、共享数据中心两种分布式会话方案
- 微服务网关鉴权 —— 适配Gateway、ShenYu、Zuul等常见网关的路由拦截认证
- 单点登录 —— 内置三种单点登录模式：无论是否跨域、是否共享Redis，都可以搞定
- OAuth2.0认证 —— 轻松搭建 OAuth2.0 服务，支持openid模式
- 二级认证 —— 在已登录的基础上再次认证，保证安全性
- Basic认证 —— 一行代码接入 Http Basic 认证
- 独立Redis —— 将权限缓存与业务缓存分离
- 临时Token认证 —— 解决短时间的Token授权问题
- 模拟他人账号 —— 实时操作任意用户状态数据
- 临时身份切换 —— 将会话身份临时切换为其它账号
- 前后端分离 —— APP、小程序等不支持Cookie的终端
- 同端互斥登录 —— 像QQ一样手机电脑同时在线，但是两个手机上互斥登录
- 多账号认证体系 —— 比如一个商城项目的user表和admin表分开鉴权
- Token风格定制 —— 内置六种Token风格，还可：自定义Token生成策略、自定义Token前缀
- 注解式鉴权 —— 优雅的将鉴权与业务代码分离
- 路由拦截式鉴权 —— 根据路由拦截鉴权，可适配restful模式
- 自动续签 —— 提供两种Token过期策略，灵活搭配使用，还可自动续签
- 会话治理 —— 提供方便灵活的会话查询接口
- 记住我模式 —— 适配[记住我]模式，重启浏览器免验证
- 密码加密 —— 提供密码加密模块，可快速MD5、SHA1、SHA256、AES、RSA加密
- 全局侦听器 —— 在用户登陆、注销、被踢下线等关键性操作时进行一些AOP操作
- 开箱即用 —— 提供SpringMVC、WebFlux等常见web框架starter集成包，真正的开箱即用
功能点的实现
登录认证
我们先梳理下登录认证流程：
- 用户提交 name + password 参数，调用登录接口。
- 登录成功，返回这个用户的 Token 会话凭证。
- 用户后续的每次请求，都携带上这个 Token。
- 服务器根据 Token 判断此会话是否登录成功。
说到本质，其实所谓的登录认证就是，服务器校验账号密码，然后为用户颁发令牌，然后用户在后续的请求中，携带token，服务器根据token判断是否可以访问。
1. 登录和注销
在认证的第一步，我们得先要进行登录，在登录的时候，我们只需要一行代码即可搞定：
// 会话登录：参数填写要登录的账号id，建议的数据类型：long | int | String， 不可以传入复杂类型，如：User、Admin 等等
StpUtil.login(Object id);
底层sa-token做了大量的工作，包括：
- 检查此账号是否之前已有登录；
- 为账号生成 Token 凭证与 Session 会话；
- 记录 Token 活跃时间；
- 通知全局侦听器，xx 账号登录成功；
- 将 Token 注入到请求上下文；
由此，Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端。
测试代码如下：
// 会话登录接口
@RequestMapping("doLogin")
public SaResult doLogin(String name, String pwd) {
// 第一步：比对前端提交的账号名称、密码
if("zhang".equals(name) && "123456".equals(pwd)) {
// 第二步：根据账号id，进行登录
StpUtil.login(10001);
return SaResult.ok("登录成功");
}
return SaResult.error("登录失败");
}
有没有发现，我们并没有给前端返回token，那么前端是怎么拿到的，其实是StpUtil.login(id) 方法利用了 Cookie 自动注入的特性，省略了你手写返回 token 的代码。Cookie 可以从后端控制往浏览器中写入 token 值，也会在前端每次发起请求时自动提交 token 值，这样我们就完成了登录认证。
但是要注意这种写法，真正在生产上是不可行的，所以我们就得需要手动将token返回给后端。
还有一些方法需要我们注意：
// 当前会话注销登录
StpUtil.logout();
// 获取当前会话是否已经登录，返回true=已登录，false=未登录
StpUtil.isLogin();
// 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
StpUtil.checkLogin();
2. token 查询
// 获取当前会话的 token 值
StpUtil.getTokenValue();
// 获取当前`StpLogic`的 token 名称
StpUtil.getTokenName();
// 获取指定 token 对应的账号id，如果未登录，则返回 null
StpUtil.getLoginIdByToken(String tokenValue);
// 获取当前会话剩余有效期（单位：s，返回-1代表永久有效）
StpUtil.getTokenTimeout();
// 获取当前会话的 token 信息参数
StpUtil.getTokenInfo();
3. 测试
这里我们来一个小的测试：
/**
* 登录测试
*/
@RestController
@RequestMapping("/acc/")
public class LoginController {
// 测试登录 ---- http://localhost:8081/acc/doLogin?name=zhang&pwd=123456
@RequestMapping("doLogin")
public SaResult doLogin(String name, String pwd) {
// 此处仅作模拟示例，真实项目需要从数据库中查询数据进行比对
if("zhang".equals(name) && "123456".equals(pwd)) {
StpUtil.login(10001);
return SaResult.ok("登录成功");
}
return SaResult.error("登录失败");
}
// 查询登录状态 ---- http://localhost:8081/acc/isLogin
@RequestMapping("isLogin")
public SaResult isLogin() {
return SaResult.ok("是否登录：" + StpUtil.isLogin());
}
// 查询 Token 信息 ---- http://localhost:8081/acc/tokenInfo
@RequestMapping("tokenInfo")
public SaResult tokenInfo() {
return SaResult.data(StpUtil.getTokenInfo());
}
// 测试注销 ---- http://localhost:8081/acc/logout
@RequestMapping("logout")
public SaResult logout() {
StpUtil.logout();
return SaResult.ok();
}
}
权限认证
所谓权限认证，核心逻辑就是判断一个账号是否拥有指定权限，深入到底层数据中，就是每个账号都会拥有一组权限码集合，框架来校验这个集合中是否包含指定的权限码。
所以现在我们的核心任务是：如何获取一个账号所拥有的权限码集合；本次操作需要验证的权限码是哪个。
1. 获取当前账号权限码集合
新建一个类，实现 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;
}
}
接口详细说明
要注意，它的调用，不需要你来直接调用，而是当你调用下面的权限校验方法的时候，它会自动执行。
2. 权限校验
// 获取：当前账号所拥有的权限集合
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. 角色校验
// 获取：当前账号所拥有的角色集合
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");
4. 权限通配符
Sa-Token允许你根据通配符指定泛权限，例如当一个账号拥有art.*的权限时，art.add、art.delete、art.update都将匹配通过。
踢人下线
所谓踢人下线，核心操作就是找到指定 loginId 对应的 Token，并设置其失效。
1. 强制注销
StpUtil.logout(10001); // 强制指定账号注销下线
StpUtil.logout(10001, "PC"); // 强制指定账号指定端注销下线
StpUtil.logoutByTokenValue("token"); // 强制指定 Token 注销下线
2. 踢人下线
StpUtil.kickout(10001); // 将指定账号踢下线
StpUtil.kickout(10001, "PC"); // 将指定账号指定端踢下线
StpUtil.kickoutByTokenValue("token"); // 将指定 Token 踢下线
强制注销 和 踢人下线 的区别在于：
- 强制注销等价于对方主动调用了注销方法，再次访问会提示：Token无效。
- 踢人下线不会清除Token信息，而是将其打上特定标记，再次访问会提示：Token已被踢下线。
路由拦截鉴权
比如需求：项目中所有接口均需要登录认证，只有 “登录接口” 本身对外开放。
1. 注册 Sa-Token 路由拦截器
@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
// 注册拦截器
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 注册 Sa-Token 拦截器，校验规则为 StpUtil.checkLogin() 登录校验。
registry.addInterceptor(new SaInterceptor(handle -> StpUtil.checkLogin()))
.addPathPatterns("/**")
.excludePathPatterns("/user/doLogin");
}
}
以上代码，我们注册了一个基于 StpUtil.checkLogin() 的登录校验拦截器，并且排除了/user/doLogin接口用来开放登录（除了/user/doLogin以外的所有接口都需要登录才能访问）。
2. 校验函数详解
自定义认证规则：new SaInterceptor(handle -> StpUtil.checkLogin()) 是最简单的写法，代表只进行登录校验功能。
@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 注册 Sa-Token 拦截器，定义详细认证规则
registry.addInterceptor(new SaInterceptor(handler -> {
// 指定一条 match 规则
SaRouter
.match("/**") // 拦截的 path 列表，可以写多个 */
.notMatch("/user/doLogin") // 排除掉的 path 列表，可以写多个
.check(r -> StpUtil.checkLogin()); // 要执行的校验动作，可以写完整的 lambda 表达式
// 根据路由划分模块，不同模块不同鉴权
SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
SaRouter.match("/orders/**", r -> StpUtil.checkPermission("orders"));
SaRouter.match("/notice/**", r -> StpUtil.checkPermission("notice"));
SaRouter.match("/comment/**", r -> StpUtil.checkPermission("comment"));
})).addPathPatterns("/**");
}
}
SaRouter.match() 匹配函数有两个参数：
参数一：要匹配的path路由；
参数二：要执行的校验函数。