RuoYi-Vue-Plus（sa-token）

一、介绍

官网：

Sa-Tokenhttps://sa-token.cc/index.html

特性：

登录与权限认证：支持用户登录和细粒度权限认证。
会话管理：提供会话创建、维护和销毁功能。
单点登录：支持单点登录，简化多应用登录流程。
OAuth2.0集成：集成OAuth2.0协议，实现安全授权与认证。
微服务网关鉴权：确保微服务间的安全访问。
轻量且易用：功能强大但易于集成和使用。

登录流程简介：

对于一些登录之后才能访问的接口（例如：查询我的账号资料），我们通常的做法是增加一层接口校验：

如果校验通过，则：正常返回数据。
如果校验未通过，则：抛出异常，告知其需要先进行登录。

用户提交 name + password 参数，调用登录接口。
登录成功，返回这个用户的 Token 会话凭证。
用户后续的每次请求，都携带上这个 Token。
服务器根据 Token 判断此会话是否登录成功。

所谓登录认证，指的就是服务器校验账号密码，为用户颁发 Token 会话凭证的过程，这个 Token 也是我们后续判断会话是否登录的关键所在。

二、集成

注：如果你使用的是 SpringBoot 3.x，只需要将 sa-token-spring-boot-starter 修改为 sa-token-spring-boot3-starter 即可。

1-添加依赖

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

2-配置文件编写

若依sa-token 配置在yml中，如下：ruoyi-admin/src/main/resources/application.yml

属性讲解：
timeout: 86400 固定有效期，必定一天过期
active-timeout: 1800 临时有效期，30分钟误操作token过期
is-concurrent：并发登录，为true时允许一起登录, 为false时新登录挤掉旧登录
is-read-cookie 是否尝试从cookie里读取token，默认不从cookie中获取，可能会有csrf攻击

# Sa-Token配置
sa-token:# token名称 (同时也是cookie名称)token-name: Authorization# token有效期 设为一天 (必定过期) 单位: 秒timeout: 86400# 多端不同 token 有效期 可查看 LoginHelper.loginByDevice 方法自定义# token最低活跃时间 (指定时间无操作就过期) 单位: 秒active-timeout: 1800# 允许动态设置 token 有效期dynamic-active-timeout: true# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录)is-concurrent: true# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token)is-share: false# 是否尝试从header里读取tokenis-read-header: true# 是否尝试从cookie里读取tokenis-read-cookie: false# token前缀token-prefix: "Bearer"# jwt秘钥jwt-secret-key: abcdefghijklmnopqrstuvwxyz

三、常用函数

1-登录、注销函数

StpUtil.login(Object id);	只此一句代码，便可以使会话登录成功，实际上，Sa-Token 在背后做了大量的工作，包括但不限于： 1-检查此账号是否之前已有登录； 2-为账号生成 Token 凭证与 Session 会话； 3-记录 Token 活跃时间； 4-通知全局侦听器，xx 账号登录成功； 5-将 Token 注入到请求上下文；你暂时不需要完整了解整个登录过程，你只需要记住关键一点：Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端。流程与思路详见：登录认证 (sa-token.cc)https://sa-token.cc/doc.html?code=25446615d46b82ca1f92853e66d5d64c63fe3a34e6a611a52458847155bff768#/use/login-auth
StpUtil.logout();	// 当前会话注销登录
StpUtil.isLogin();	// 获取当前会话是否已经登录，返回true=已登录，false=未登录
StpUtil.checkLogin();	// 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`

2-强制注销

StpUtil.logout(10001);                    // 强制指定账号注销下线 
StpUtil.logout(10001, "PC");              // 强制指定账号指定端注销下线 
StpUtil.logoutByTokenValue("token");      // 强制指定 Token 注销下线

3-踢人下线

StpUtil.kickout(10001);                    // 将指定账号踢下线 
StpUtil.kickout(10001, "PC");              // 将指定账号指定端踢下线
StpUtil.kickoutByTokenValue("token");      // 将指定 Token 踢下线

强制注销和踢人下线的区别在于：

强制注销等价于对方主动调用了注销方法，再次访问会提示：Token无效。
踢人下线不会清除Token信息，而是将其打上特定标记，再次访问会提示：Token已被踢下线。

4-会话函数

StpUtil.getLoginId();	// 获取当前会话账号id, 如果未登录，则抛出异常：`NotLoginException`
类似上面	StpUtil.getLoginIdAsString(); // 获取当前会话账号id, 并转化为`String`类型 StpUtil.getLoginIdAsInt(); // 获取当前会话账号id, 并转化为`int`类型 StpUtil.getLoginIdAsLong(); // 获取当前会话账号id, 并转化为`long`类型
StpUtil.getLoginIdDefaultNull();	/ 获取当前会话账号id, 如果未登录，则返回 null
StpUtil.getLoginId(T defaultValue);	// 获取当前会话账号id, 如果未登录，则返回默认值（`defaultValue`可以为任意类型）

5-Token查询

StpUtil.getTokenValue();	// 获取当前会话的 token 值
StpUtil.getTokenName();	// 获取当前`StpLogic`的 token 名称
StpUtil.getLoginIdByToken(String tokenValue);	// 获取指定 token 对应的账号id，如果未登录，则返回 null
StpUtil.getTokenTimeout();	// 获取当前会话剩余有效期（单位：s，返回-1代表永久有效）
StpUtil.getTokenInfo();	// 获取当前会话的 token 信息参数

关于token参数详解：

{"code": 200,"msg": "ok","data": {"tokenName": "satoken",           // token名称"tokenValue": "e67b99f1-3d7a-4a8d-bb2f-e888a0805633",      // token值"isLogin": true,                  // 此token是否已经登录"loginId": "10001",               // 此token对应的LoginId，未登录时为null"loginType": "login",              // 账号类型标识"tokenTimeout": 2591977,          // token剩余有效期 (单位: 秒)"sessionTimeout": 2591977,        // Account-Session剩余有效时间 (单位: 秒)"tokenSessionTimeout": -2,        // Token-Session剩余有效时间 (单位: 秒) (-2表示系统中不存在这个缓存)"tokenActiveTimeout": -1,         // token 距离被冻结还剩的时间 (单位: 秒)"loginDevice": "default-device"   // 登录设备类型 },
}

四、权限

自行查看 api接口

权限认证 (sa-token.cc)https://sa-token.cc/doc.html?code=25446615d46b82ca1f92853e66d5d64c63fe3a34e6a611a52458847155bff768#/use/jur-auth

5-注解鉴权

注解鉴权 —— 优雅的将鉴权与业务代码分离！

@SaCheckLogin: 登录校验 —— 只有登录之后才能进入该方法。
@SaCheckRole("admin"): 角色校验 —— 必须具有指定角色标识才能进入该方法。
@SaCheckPermission("user:add"): 权限校验 —— 必须具有指定权限才能进入该方法。
@SaCheckSafe: 二级认证校验 —— 必须二级认证之后才能进入该方法。
@SaCheckBasic: HttpBasic校验 —— 只有通过 Basic 认证后才能进入该方法。
@SaIgnore：忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权。
@SaCheckDisable("comment")：账号服务封禁校验 —— 校验当前账号指定服务是否被封禁。

你必须手动将 Sa-Token 的全局拦截器注册到你项目中

官网文档：

路由拦截鉴权 (sa-token.cc)https://sa-token.cc/doc.html?code=25446615d46b82ca1f92853e66d5d64c63fe3a34e6a611a52458847155bff768#/use/route-check?id=_1%E3%80%81%E6%B3%A8%E5%86%8C-sa-token-%E8%B7%AF%E7%94%B1%E6%8B%A6%E6%88%AA%E5%99%A8

下面是若依中的实现：

@RequiredArgsConstructor
@Slf4j
@Configuration
public class SaTokenConfig implements WebMvcConfigurer {private final SecurityProperties securityProperties;/*** 注册sa-token的拦截器*/@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 注册路由拦截器，自定义验证规则registry.addInterceptor(new SaInterceptor(handler -> {AllUrlHandler allUrlHandler = SpringUtils.getBean(AllUrlHandler.class);// 登录验证 -- 排除多个路径SaRouter// 获取所有的.match(allUrlHandler.getUrls())// 对未排除的路径进行检查.check(() -> {// 检查是否登录 是否有tokenStpUtil.checkLogin();// 有效率影响 用于临时测试// if (log.isDebugEnabled()) {//     log.info("剩余有效时间: {}", StpUtil.getTokenTimeout());//     log.info("临时有效时间: {}", StpUtil.getTokenActiveTimeout());// }});})).addPathPatterns("/**")// 排除不需要拦截的路径.excludePathPatterns(securityProperties.getExcludes());}@Beanpublic StpLogic getStpLogicJwt() {// Sa-Token 整合 jwt (简单模式)return new StpLogicJwtForSimple();}/*** 权限接口实现(使用bean注入方便用户替换)*/@Beanpublic StpInterface stpInterface() {return new SaPermissionImpl();}/*** 自定义dao层存储*/@Beanpublic SaTokenDao saTokenDao() {return new PlusSaTokenDao();}}

五、session 会话

在 Sa-Token 中，Session 分为三种，分别是：

Account-Session: 指的是框架为每个账号id 分配的 Session
Token-Session: 指的是框架为每个 token 分配的 Session
Custom-Session: 指的是以一个特定的值作为SessionId，来分配的 Session

// 在登录时缓存 user 对象 
StpUtil.getSession().set("user", user);// 然后我们就可以在任意处使用这个 user 对象
SysUser user = (SysUser) StpUtil.getSession().get("user");

1-Account-Session 绑定当前用户id ，api如下

// 获取当前账号 id 的 Account-Session (必须是登录后才能调用)
StpUtil.getSession();// 获取当前账号 id 的 Account-Session, 并决定在 Session 尚未创建时，是否新建并返回
StpUtil.getSession(true);// 获取账号 id 为 10001 的 Account-Session
StpUtil.getSessionByLoginId(10001);// 获取账号 id 为 10001 的 Account-Session, 并决定在 Session 尚未创建时，是否新建并返回
StpUtil.getSessionByLoginId(10001, true);// 获取 SessionId 为 xxxx-xxxx 的 Account-Session, 在 Session 尚未创建时, 返回 null 
StpUtil.getSessionBySessionId("xxxx-xxxx");

2- Token-Session 绑定当前token的信息

// 获取当前 Token 的 Token-Session 对象
StpUtil.getTokenSession();// 获取指定 Token 的 Token-Session 对象
StpUtil.getTokenSessionByToken(token);

3-Custom-Session 自定义sessionid

比如，下面goods-10001是某个商品的id

// 查询指定key的Session是否存在
SaSessionCustomUtil.isExists("goods-10001");// 获取指定key的Session，如果没有，则新建并返回
SaSessionCustomUtil.getSessionById("goods-10001");// 获取指定key的Session，如果没有，第二个参数决定是否新建并返回  
SaSessionCustomUtil.getSessionById("goods-10001", false);   // 删除指定key的Session
SaSessionCustomUtil.deleteSessionById("goods-10001");

官网还提供一些 session 读写的api ，自行查看

Session会话 (sa-token.cc)https://sa-token.cc/doc.html?code=25446615d46b82ca1f92853e66d5d64c63fe3a34e6a611a52458847155bff768#/use/session?id=%E5%9C%A8-session-%E4%B8%8A%E5%AD%98%E5%8F%96%E5%80%BC

六、sa-token 登录拦截器

1、路由权限拦截器

类路径：com.ruoyi.framework.config.SaTokenConfig，实现WebMvcConfigurer 接口
1-通过 registry.addInterceptor(new SaInterceptor(handler -> { } 添加 SaInterceptor 拦截器
2-在拦截器中可以自定义登录、角色、权限的校验

登录校验 -- 拦截所有路由，并排除/user/doLogin 用于开放登录 SaRouter.match("/**", "/user/doLogin", r -> StpUtil.checkLogin());
角色校验 -- 拦截以 admin 开头的路由，必须具备 admin 角色或者 super-admin 角色才可以通过认证 SaRouter.match("/admin/**", r -> StpUtil.checkRoleOr("admin", "super-admin")); 权限校验 -- 不同模块校验不同权限 SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));

3- 排除不需要拦截的路径（该配置在 ruoyi-admin 模块的yml中配置）
.excludePathPatterns(securityProperties.getExcludes());

其他注入
通过 getStpLogicJwt 方法，注入 tpLogic 类是为了整合Jwt
通过 stpInterface方法，注入 StpInterface 接口，手动去实现
注入SaTokenDao ，实现对redis对sotoken的读写

@RequiredArgsConstructor
@Slf4j
@Configuration
public class SaTokenConfig implements WebMvcConfigurer {private final SecurityProperties securityProperties;/*** 注册sa-token的拦截器*/@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 注册路由拦截器，自定义验证规则registry.addInterceptor(new SaInterceptor(handler -> {AllUrlHandler allUrlHandler = SpringUtils.getBean(AllUrlHandler.class);// 登录验证 -- 排除多个路径SaRouter// 获取所有的.match(allUrlHandler.getUrls())// 对未排除的路径进行检查.check(() -> {// 检查是否登录 是否有tokenStpUtil.checkLogin();// 有效率影响 用于临时测试// if (log.isDebugEnabled()) {//     log.info("剩余有效时间: {}", StpUtil.getTokenTimeout());//     log.info("临时有效时间: {}", StpUtil.getTokenActiveTimeout());// }});})).addPathPatterns("/**")// 排除不需要拦截的路径.excludePathPatterns(securityProperties.getExcludes());}@Beanpublic StpLogic getStpLogicJwt() {// Sa-Token 整合 jwt (简单模式)return new StpLogicJwtForSimple();}/*** 权限接口实现(使用bean注入方便用户替换)*/@Beanpublic StpInterface stpInterface() {return new SaPermissionImpl();}/*** 自定义dao层存储* PlusSaTokenDao  Sa-Token持久层接口(使用框架自带RedisUtils实现 协议统一)*/@Beanpublic SaTokenDao saTokenDao() {return new PlusSaTokenDao();}}

2- saTokenDao

上面配置中，自定义dao层存储，注入 PlusSaTokenDao 作为 Sa-Token持久层接口(使用框架自带RedisUtils实现协议统一) ，

@Beanpublic SaTokenDao saTokenDao() {return new PlusSaTokenDao();}

若果不去自己实现sotoken的DAO层接口，框架默认会基于内存区存储，如下 SaTokenDaoDefaultImpl 类实现 SaTokenDao

public class SaTokenDaoDefaultImpl implements SaTokenDao {public Map<String, Object> dataMap = new ConcurrentHashMap();public Map<String, Long> expireMap = new ConcurrentHashMap();.......

3-sotoken Jwt 介绍

JWT就是上述流程当中token的一种具体实现方式，其全称是JSON Web Token，

通俗地说，JWT的本质就是一个字符串，它是将用户信息保存到一个Json字符串中，然后进行编码后得到一个JWT token，并且这个JWT token带有签名信息，接收后可以校验是否被篡改，所以可以用于在各方之间安全地将信息作为Json对象传输。JWT的详细博文如下：

JWT详解-CSDN博客文章浏览阅读10w+次，点赞927次，收藏4.6k次。本文从本人博客搬运，原文格式更加美观，可以移步原文阅读：JWT详解JWT简介1.什么是JWT在介绍JWT之前，我们先来回顾一下利用token进行用户身份验证的流程：客户端使用用户名和密码请求登录服务端收到请求，验证用户名和密码验证成功后，服务端会签发一个token，再把这个token返回给客户端客户端收到token后可以把它存储起来，比如放到cookie中客户端每次向服务端请求资源时需要携带服务端签发的token，可以在cookie或者header中携带服务端收到请求，然后去验证客户端请_jwt详解https://blog.csdn.net/weixin_45070175/article/details/118559272

1-集成

依赖：ruoyi-common/pom.xml 中

        <!-- Sa-Token 整合 jwt --><dependency><groupId>cn.dev33</groupId><artifactId>sa-token-jwt</artifactId></dependency>

配置秘钥：上面 ruoyi-amin配置文件sotoken中配置

# Sa-Token配置
sa-token:# jwt秘钥jwt-secret-key: abcdefghijklmnopqrstuvwxyz

com.ruoyi.framework.config.SaTokenConfig 类中注入

 @Beanpublic StpLogic getStpLogicJwt() {// Sa-Token 整合 jwt (简单模式)return new StpLogicJwtForSimple();}

整合文档参考：

和 jwt 集成 (sa-token.cc)https://sa-token.cc/doc.html?code=25446615d46b82ca1f92853e66d5d64c63fe3a34e6a611a52458847155bff768#/plugin/jwt-extend