Sa-Token 轻松入门
Sa-Token是什么?
一个轻量级 Java 权限认证框架，让鉴权变得简单、优雅！
Sa-Token 介绍
github仓库地址:https://github.com/dromara/sa-token
Sa-Token 是一个轻量级 Java 权限认证框架，主要解决：登录认证、权限认证、单点登录、OAuth2.0、分布式Session会话、微服务网关鉴权 等一系列权限相关问题。
这里插上一句,相信大家之前肯定都使用过,Spring Security或者Shiro,相比于这两个权限框架,Sa-Token的使用极其简单,简化了很多步骤.
Sa-Token功能一览
- 登录认证 —— 单端登录、多端登录、同端互斥登录、七天内免登录
- 权限认证 —— 权限认证、角色认证、会话二级认证
- Session会话 —— 全端共享Session、单端独享Session、自定义Session
- 踢人下线 —— 根据账号id踢人下线、根据Token值踢人下线
- 账号封禁 —— 指定天数封禁、永久封禁、设定解封时间
- 持久层扩展 —— 可集成Redis、Memcached等专业缓存中间件，重启数据不丢失
- 分布式会话 —— 提供jwt集成、共享数据中心两种分布式会话方案
- 微服务网关鉴权 —— 适配Gateway、ShenYu、Zuul等常见网关的路由拦截认证
- 单点登录 —— 内置三种单点登录模式：无论是否跨域、是否共享Redis，都可以搞定
- OAuth2.0认证 —— 基于RFC-6749标准编写，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集成包，真正的开箱即用
Sa-Token入门小示例
引入Sa-Token的依赖,这里使用的是Spring Boot 所以这里引入的jar包将是Spring Mvc环境,Sa-Token提供了多种环境下使用的jar包
如果你使用的框架基于 ServletAPI 构建（ SpringMVC、SpringBoot等 ），请引入此包
<dependency>
<groupId>cn.dev33groupId>
<artifactId>sa-token-spring-boot-starterartifactId>
<version>1.30.0version>
dependency>
要是使用Gradle就引入以下依赖
implementation 'cn.dev33:sa-token-spring-boot-starter:1.30.0'
注：JDK版本：v1.8+
设置配置文件
你可以零配置启动项目 ，但同时你也可以在 application.yml 中增加如下配置，定制性使用框架：
server:
# 端口
port: 8081
# Sa-Token配置
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: false
# token风格
token-style: uuid
# 是否输出操作日志
is-log: false
要是你喜欢使用properties的话呢,自己鼓捣一下就好啦
springboot properties与yml 配置文件的区别
创建启动类
在项目中建一个启动类
@SpringBootApplication
public class SaTokenDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SaTokenDemoApplication.class, args);
// 打印Sa-Token配置
System.out.println(SaManager.getConfig());
}
}
搞定!
创建一个测试类
package cn.lsqo.controller;
import cn.dev33.satoken.stp.StpUtil;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/test")
public class UserController {
@RequestMapping("/login")
public String login(String username, String password) {
if("123".equals(username) && "123".equals(password)) {
StpUtil.login(10001);
return "success";
}
return "error";
}
@RequestMapping("/isLogin")
public Boolean isLogin() {
// 当前是否登录
return StpUtil.isLogin();
}
}
运行结果
登录
查看当前会话是否已经登录
返回为true证明当前会话已经登录啦
这个示例相信大家有初步了解啦,接下来我们就详细看一下他应该如何使用吧
登录认证
通常我们在对需要登录才能访问的接口进行访问时,我们一般会对接口加一层校验,比如说通过拦截器判断请求头中是否携带token以及校验token的合法性来判断该用户是否已经登录
登录认证,指的就是服务器校验账号密码,为用户颁发 Token 会话凭证的过程
在入门小示例中,我们看到只需要一句代码,便可以登录成功,实际上通过Sa-Token的官方文档得知,他在背后做了大量的事情,比如:
- 检查此账号是否已被封禁
- 检查此账号是否之前已有登录
- 为账号生成
Token凭证与Session会话- 通知全局侦听器，xx 账号登录成功
- 将
Token注入到请求上下文- 等等其它工作……
- 你暂时不需要完整的了解整个登录过程，你只需要记住关键一点：
Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端。
所以我们登录接口只需要校验用户名及其密码是否正确后,使用下列这一句代码就能做到登录
// 里面传入账号id
StpUtil.login(Object id);
在这里发现并没有返回一个token,看官方文档得知
StpUtil.login(id)方法利用了 Cookie 自动注入的特性，省略了你手写返回 Token 的代码。
- Cookie 可以从后端控制往浏览器中写入 Token 值。
- Cookie 会在每次请求时自动提交 Token 值。
因此，在 Cookie 功能的加持下，我们可以仅靠
StpUtil.login(id)一句代码就完成登录认证。
以下是一些登录相关方法的使用
// 当前会话注销登录
StpUtil.logout();
// 获取当前会话是否已经登录，返回true=已登录，false=未登录
StpUtil.isLogin();
// 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
//异常 NotLoginException 代表当前会话暂未登录，可能的原因有很多： 前端没有提交 Token、前端提交的 Token 是无效的、前端提交的 Token 已经过期 …… 等等
StpUtil.checkLogin();
// 获取当前会话账号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);
Token查询(在前后端分离的场景下,我们可以通过此方法返回给前端Token,让前端设置到请求头中)
并且我们可以在配置文件中设置token的格式比如uuid,也可以设置请求头中的key
// 获取当前会话的token值
StpUtil.getTokenValue();
// 获取当前`StpLogic`的token名称
StpUtil.getTokenName();
// 获取指定token对应的账号id，如果未登录，则返回 null
StpUtil.getLoginIdByToken(String tokenValue);
// 获取当前会话剩余有效期（单位：s，返回-1代表永久有效）
StpUtil.getTokenTimeout();
// 获取当前会话的token信息参数
StpUtil.getTokenInfo();
权限认证
Sa-Token的权限认证非常简单,每一个账号都会拥有一个对应的权限集合
只需要实现实现 StpInterface接口
loginType为在多账号体系下,比如前台用户以及后台用户的权限区分我们将通过loginTyoe来实现
@Component
public class StpInterfaceImpl implements StpInterface {
/**
* 返回一个账号所拥有的权限码集合
*/
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
// 这里有一个点,loginType这个参数为多账号体系下判断账号类型使用
List<String> list = new ArrayList<String>();
list.add("admin-add");
list.add("admin-delete");
list.add("user-update");
return list;
}
/**
* 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
*/
@Override
public List<String> getRoleList(Object loginId, String loginType) {
List<String> list = new ArrayList<String>();
list.add("admin");
return list;
}
}
鉴权相关的api
// 获取：当前账号所拥有的权限集合
StpUtil.getPermissionList();
// 判断：当前账号是否含有指定权限, 返回true或false
StpUtil.hasPermission("user-update");
// 校验：当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException
StpUtil.checkPermission("user-update");
// 校验：当前账号是否含有指定权限 [指定多个，必须全部验证通过]
StpUtil.checkPermissionAnd("user-update", "user-delete");
// 校验：当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
StpUtil.checkPermissionOr("user-update", "user-delete");
// 获取：当前账号所拥有的角色集合
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");
我们可以通过全局异常捕捉来返回给前端信息
/**
* 全局异常处理
*/
@ControllerAdvice
public class GlobalException {
// 全局异常拦截（拦截项目中的所有异常）
@ResponseBody
@ExceptionHandler
public AjaxJson handlerException(Exception e, HttpServletRequest request, HttpServletResponse response)
throws Exception {
// 打印堆栈，以供调试
System.out.println("全局异常---------------");
e.printStackTrace();
// 不同异常返回不同状态码
AjaxJson aj = null;
if (e instanceof NotLoginException) { // 如果是未登录异常
NotLoginException ee = (NotLoginException) e;
aj = AjaxJson.getNotLogin().setMsg(ee.getMessage());
}
else if(e instanceof NotRoleException) { // 如果是角色异常
NotRoleException ee = (NotRoleException) e;
aj = AjaxJson.getNotJur("无此角色：" + ee.getRole());
}
else if(e instanceof NotPermissionException) { // 如果是权限异常
NotPermissionException ee = (NotPermissionException) e;
aj = AjaxJson.getNotJur("无此权限：" + ee.getPermission());
}
else if(e instanceof DisableLoginException) { // 如果是被封禁异常
DisableLoginException ee = (DisableLoginException) e;
aj = AjaxJson.getNotJur("账号被封禁：" + ee.getDisableTime() + "秒后解封");
}
else { // 普通异常, 输出：500 + 异常信息
aj = AjaxJson.getError(e.getMessage());
}
// 返回给前端
return aj;
}
}
Sa-Token允许你根据通配符指定泛权限，例如当一个账号拥有
user*的权限时，user-add、user-delete、user-update都将匹配通过
// 当拥有 user* 权限时
StpUtil.hasPermission("user-add"); // true
StpUtil.hasPermission("user-update"); // true
StpUtil.hasPermission("art-add"); // false
// 当拥有 *-delete 权限时
StpUtil.hasPermission("user-add"); // false
StpUtil.hasPermission("user-delete"); // true
StpUtil.hasPermission("art-delete"); // true
// 当拥有 *.js 权限时
StpUtil.hasPermission("index.js"); // true
StpUtil.hasPermission("index.css"); // false
StpUtil.hasPermission("index.html"); // false
然后就是大家都喜欢的注解鉴权啦
注解鉴权
如果觉得这样麻烦的话,我们也能通过打注解的方式来实现
@SaCheckLogin: 登录认证 —— 只有登录之后才能进入该方法。@SaCheckRole("admin"): 角色认证 —— 必须具有指定角色标识才能进入该方法。@SaCheckPermission("user:add"): 权限认证 —— 必须具有指定权限才能进入该方法。@SaCheckSafe: 二级认证校验 —— 必须二级认证之后才能进入该方法。@SaCheckBasic: HttpBasic认证 —— 只有通过 Basic 认证后才能进入该方法。Sa-Token 使用全局拦截器完成注解鉴权功能，为了不为项目带来不必要的性能负担，拦截器默认处于关闭状态
因此，为了使用注解鉴权，你必须手动将 Sa-Token 的全局拦截器注册到你项目中
注册拦截器
@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 注册注解拦截器，并排除不需要注解鉴权的接口地址 (与登录拦截器无关)
registry.addInterceptor(new SaAnnotationInterceptor()).addPathPatterns("/**");
}
}
然后就搞定啦,注解鉴权相关的使用如下
// 登录认证：只有登录之后才能进入该方法
@SaCheckLogin
@RequestMapping("info")
public String info() {
return "查询用户信息";
}
// 角色认证：必须具有指定角色才能进入该方法
@SaCheckRole("super-admin")
@RequestMapping("add")
public String add() {
return "用户增加";
}
// 权限认证：必须具有指定权限才能进入该方法
@SaCheckPermission("user-add")
@RequestMapping("add")
public String add() {
return "用户增加";
}
// 二级认证：必须二级认证之后才能进入该方法
@SaCheckSafe()
@RequestMapping("add")
public String add() {
return "用户增加";
}
// Http Basic 认证：只有通过 Basic 认证后才能进入该方法
@SaCheckBasic(account = "sa:123456")
@RequestMapping("add")
public String add() {
return "用户增加";
}
@SaCheckRole与@SaCheckPermission注解可设置校验模式，例如：
// 注解式鉴权：只要具有其中一个权限即可通过校验
@RequestMapping("atJurOr")
@SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)
public SaResult atJurOr() {
return SaResult.data("用户信息");
}
多账号体系使用
实例:
比如说，对于原生
StpUtil类，我们只做admin账号权限认证，而对于user账号，我们则：
- 新建一个新的权限认证类，比如：
StpUserUtil.java。- 将
StpUtil.java类的全部代码复制粘贴到StpUserUtil.java里。- 更改一下其
LoginType， 比如：
public class StpUserUtil {
/**
* 账号体系标识
*/
public static final String TYPE = "user"; // 将 LoginType 从`login`改为`user`
// 其它代码 ...
}
在上面我们说到进行权限加载的时候有一个LoginType,我们通过LoginType来判断当前账号属于哪一个体系
在多账号体系下使用注解鉴权需要在注解中加入当前账号体系的type,例如:
// 通过type属性指定此注解校验的是我们自定义的`StpUserUtil`，而不是原生`StpUtil`
@SaCheckLogin(type = StpUserUtil.TYPE)
@RequestMapping("info")
public String info() {
return "查询用户信息";
}
注：
@SaCheckRole("xxx")、@SaCheckPermission("xxx")同理，亦可根据type属性指定其校验的账号体系，此属性默认为""，代表使用原生StpUtil账号体系。
这些已经够一个足够大部分项目的一个基本使用啦
Sa-Token还提供了单点登录,Oauth2.0,以及微服务中的一些使用.