springboot整合Sa-Token实现登录认证和权限校验(万字长文)

目前在国内的后端开发中,常用的安全框架有spring security、shiro。现在,介绍一款由国人开发的安全框架Sa-Token。这个框架完全由国人开发,所提供的Api文档和一些设置都是比较符合国人的开发习惯的,本次就来介绍一下如何在spring boot框架中整合Sa-Token框架,以实现我们最常使用的登录认证和权限校验;

Sa-Token的官网地址如下:
Sa-Token

Sa-Token 是由国人开发的 一个轻量级 Java 权限认证框架,主要解决:登录认证权限认证单点登录OAuth2.0分布式Session会话微服务网关鉴权 等一系列权限相关问题。

版本:spring boot3.15、Sa-Token1.37.0

1、新建一个spring boot项目,并导入一些起始的依赖:
 


            com.alibaba
            fastjson
            2.0.32
        

        
            cn.hutool
            hutool-all
            5.8.18
        
        
            com.github.xiaoymin
            knife4j-openapi3-jakarta-spring-boot-starter
            4.3.0
        

        
        
            cn.dev33
            sa-token-spring-boot3-starter
            1.37.0
        

        
            com.baomidou
            mybatis-plus-boot-starter
            3.5.3.1
        

        
            org.springframework.boot
            spring-boot-starter-web
        

        
            com.mysql
            mysql-connector-j
            runtime
        
        
            org.projectlombok
            lombok
            true
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        

2、新建五张数据表,来展示登录认证和权限校验:


1、用户表

CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(50) NOT NULL UNIQUE,
  password VARCHAR(100) NOT NULL,
  email VARCHAR(100) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2、角色表

CREATE TABLE roles (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(50) NOT NULL UNIQUE,
  description VARCHAR(255),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

3、权限表

CREATE TABLE permissions (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(50) NOT NULL UNIQUE,
  description VARCHAR(255),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

4、用户角色表

CREATE TABLE user_roles (
  id INT AUTO_INCREMENT PRIMARY KEY,
  user_id INT NOT NULL,
  role_id INT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id),
  FOREIGN KEY (role_id) REFERENCES roles(id)
);

5、角色权限表

CREATE TABLE role_permissions (
  id INT AUTO_INCREMENT PRIMARY KEY,
  role_id INT NOT NULL,
  permission_id INT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (role_id) REFERENCES roles(id),
  FOREIGN KEY (permission_id) REFERENCES permissions(id)
);

3、现在我们开始进行基于Sa-Token进行的登录校验和权限认证:
 

与spring security不同的是,引入了Sa-Token的依赖之后。并不会自动生效,需要我们自己编写相应的逻辑代码;

写一个TestController,用来进行测试;

@RestController
@RequestMapping("/test")
public class TestController {


    @GetMapping("/hello")
    public String hello() {
        System.out.println("说hello啊");
        return "test接口的hello";
    }
    
}

我们现在启动项目,并访问/test/hello接口,发现能够正常访问。这一点与spring security是不同的,spring security默认会拦截所有请求;

Sa-Token已经为我们编写了很多我们经常使用的功能,我们只需要在yml配置文件中进行配置即可。以下是一些常用的配置:
 

############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
sa-token: 
    # token 名称(同时也是 cookie 名称)
    token-name: satoken
    # token 有效期(单位:秒) 默认30天,-1 代表永久有效
    timeout: 2592000
    # token 最低活跃频率(单位:秒),如果 token 超过此时间没有访问系统就会被冻结,默认-1 代表不限制,永不冻结
    active-timeout: -1
    # 是否允许同一账号多地同时登录 (为 true 时允许一起登录, 为 false 时新登录挤掉旧登录)
    is-concurrent: true
    # 在多人登录同一账号时,是否共用一个 token (为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token)
    is-share: true
    # token 风格(默认可取值:uuid、simple-uuid、random-32、random-64、random-128、tik)
    token-style: uuid
    # 是否输出操作日志 
    is-log: true

3.1、登录认证:

使用Sa-Token进行登录认证是非常简单的,只需要一句代码就可以搞定:

// 会话登录:参数填写要登录的账号id,建议的数据类型:long | int | String, 不可以传入复杂类型,如:User、Admin 等等
StpUtil.login(Object id);     

只此一句代码,便可以使会话登录成功,实际上,Sa-Token 在背后做了大量的工作,包括但不限于:

  1. 检查此账号是否之前已有登录;
  2. 为账号生成 Token 凭证与 Session 会话;
  3. 记录 Token 活跃时间;
  4. 通知全局侦听器,xx 账号登录成功;
  5. 将 Token 注入到请求上下文;
  6. 等等其它工作……

我们暂时不需要完整了解整个登录过程,只需要记住关键一点:Sa-Token 为这个账号创建了一个Token凭证,且通过 Cookie 上下文返回给了前端

一个登录接口:

@Autowired
    IUsersService usersService;

    @PostMapping("/login")
public SaResult login(String username, String password){
//根据用户名从数据库中查询
        Users users = usersService.getOne(new LambdaQueryWrapper().eq(Users::getUsername, username));
        if(users == null){
            return SaResult.error("用户名不存在");
        }
        if(!users.getPassword().equals(password)){
    return SaResult.error("密码错误");
    }
//根据用户id登录
        StpUtil.login(users.getId());
        return SaResult.ok("登录成功");
    }

运行检验:
springboot整合Sa-Token实现登录认证和权限校验(万字长文)_第1张图片

发现确实能够登录成功。

此处仅仅做了会话登录,但并没有主动向前端返回 token 信息。 是因为不需要吗?严格来讲是需要的,只不过 StpUtil.login(id) 方法利用了 Cookie 自动注入的特性,省略了你手写返回 token 的代码。

如果你对 Cookie 功能还不太了解,也不用担心,我们会在之后的 [ 前后端分离 ] 章节中详细的阐述 Cookie 功能,现在你只需要了解最基本的两点:

  • Cookie 可以从后端控制往浏览器中写入 token 值。
  • Cookie 会在前端每次发起请求时自动提交 token 值。

因此,在 Cookie 功能的加持下,我们可以仅靠 StpUtil.login(id) 一句代码就完成登录认证。

除了登录方法,我们还需要:

// 当前会话注销登录
StpUtil.logout();

// 获取当前会话是否已经登录,返回true=已登录,false=未登录
StpUtil.isLogin();

// 检验当前会话是否已经登录, 如果未登录,则抛出异常:`NotLoginException`
StpUtil.checkLogin();

异常 NotLoginException 代表当前会话暂未登录,可能的原因有很多: 前端没有提交 token、前端提交的 token 是无效的、前端提交的 token 已经过期 …… 等等

还有一些登录过程中常用的方法:

// 获取当前会话账号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 值
StpUtil.getTokenValue();

// 获取当前`StpLogic`的 token 名称
StpUtil.getTokenName();

// 获取指定 token 对应的账号id,如果未登录,则返回 null
StpUtil.getLoginIdByToken(String tokenValue);

// 获取当前会话剩余有效期(单位:s,返回-1代表永久有效)
StpUtil.getTokenTimeout();

// 获取当前会话的 token 信息参数
StpUtil.getTokenInfo();

3.1.1前后端分离模式下的登录(无cookie模式)

无 Cookie 模式:特指不支持 Cookie 功能的终端,通俗来讲就是我们常说的 —— 前后端分离模式

常规 Web 端鉴权方法,一般由 Cookie模式 完成,而 Cookie 有两个特性:

  1. 可由后端控制写入。
  2. 每次请求自动提交。

这就使得我们在前端代码中,无需任何特殊操作,就能完成鉴权的全部流程(因为整个流程都是后端控制完成的)

而在app、小程序等前后端分离场景中,一般是没有 Cookie 这一功能的,此时大多数人都会一脸懵逼,咋进行鉴权啊?

见招拆招,其实答案很简单:

  • 不能后端控制写入了,就前端自己写入。(后端将登录成功之后生成的Token 传递到前端
  • 每次请求不能自动提交了,那就手动提交。(前端将登陆成功后获取的Token封装到请求头中每次请求时都携带后端将其读取出来,并判断用户信息

修改我们之前写的登录接口,返回token给前端;

 @PostMapping("/login")
public SaResult login(String username, String password){
//根据用户名从数据库中查询
        Users users = usersService.getOne(new LambdaQueryWrapper().eq(Users::getUsername, username));
        if(users == null){
            return SaResult.error("用户名不存在");
        }
        if(!users.getPassword().equals(password)){
    return SaResult.error("密码错误");
    }
//根据用户id登录,第1步,先登录上
        StpUtil.login(users.getId());
        // 第2步,获取 Token  相关参数 
        SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
        // 第3步,返回给前端 
        return SaResult.data(tokenInfo);
    }

在进行一次登录:
springboot整合Sa-Token实现登录认证和权限校验(万字长文)_第2张图片

可以看到登录成功之后,返回了很多相关的数据,而我们的token也在其中,那么前端就可以将token取出来放到一个状态管理器(pinia中),并且在每次请求时都将token放在请求头中。

如果你对 Cookie 非常了解,那你就会明白,所谓 Cookie ,本质上就是一个特殊的header参数而已, 而既然它只是一个 header 参数,我们就能手动模拟实现它,从而完成鉴权操作。

3.1.2路由拦截鉴权:

假设我们有如下需求:

项目中所有接口均需要登录认证,只有 “登录接口” 本身对外开放

我们怎么实现呢?给每个接口加上鉴权注解?手写全局拦截器?似乎都不是非常方便。

在这个需求中我们真正需要的是一种基于路由拦截的鉴权模式,那么在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("/users/login");
    }
    
}

以上代码,我们注册了一个基于 StpUtil.checkLogin() 的登录校验拦截器,并且排除了/user/login接口用来开放登录(除了/user/login以外的所有接口都需要登录才能访问)这就与我们spring security有了一点点相似了,因为spring security默认的就是所有的接口都被拦截到。

我们再启动项目,并访问我们最开始写的/test/hello接口;

springboot整合Sa-Token实现登录认证和权限校验(万字长文)_第3张图片

可以看到这个接口被拦截了。那么我们带上之前登录成功,生成的token之后再去访问呢?

springboot整合Sa-Token实现登录认证和权限校验(万字长文)_第4张图片

可以看到我们成功访问了这个接口;

new SaInterceptor(handle -> StpUtil.checkLogin()) 是最简单的写法,代表只进行登录校验功能。实际上Sa-Token还可以实现一些更详细的校验规则,在Sa-Token的官网上可以看到。

3.2权限认证:

我们已经了解了常用的登录认证方法,接下来,我们来看一下权限认证;

1、获取当前用户的权限码集合:

因为每个项目的需求不同,其权限设计也千变万化,因此 [ 获取当前账号权限码集合 ] 这一操作不可能内置到框架中, 所以 Sa-Token 将此操作以接口的方式暴露给你,以方便你根据自己的业务逻辑进行重写。

你需要做的就是新建一个类,实现 StpInterface接口

/**
 * 自定义权限加载接口实现类
 */
@Component    // 保证此类被 SpringBoot 扫描,完成 Sa-Token 的自定义权限验证扩展
public class StpInterfaceImpl implements StpInterface {

    /**
     * 返回一个账号所拥有的权限码集合 
     */

//    角色权限表
    @Autowired
    IRolePermissionsService rolePermissionsService;
//    用户角色表
    @Autowired
    IUserRolesService userRolesService;
//权限表
    @Autowired
    IPermissionsService permissionsService;
    
//    角色表
    @Autowired
    IRolesService rolesService;
    
    @Override
    public List getPermissionList(Object loginId, String loginType) {
//        根据用户id从用户角色表中获取角色id
        List roleIds = userRolesService.list(new LambdaQueryWrapper()
                .eq(UserRoles::getUserId,Integer.parseInt(loginId.toString())));
        List rolesList = roleIds.stream().map(UserRoles::getRoleId).toList();
if (!(rolesList.size() >0)){
//    没有任何权限
    return null;
}
        List list = new ArrayList<>();
           
        rolesList.forEach(roleId ->{
            // 根据角色id从角色权限表中获取权限id   
            List rolePermissions = rolePermissionsService.list(new LambdaQueryWrapper().
                    eq(RolePermissions::getRoleId, roleId));
            // 根据权限id从权限表中获取权限名称
            rolePermissions.forEach(permissionsId->{
                Permissions permissions = permissionsService.getById(permissionsId.getPermissionId());
                list.add(permissions.getName());
            });
        });

        // 返回用户所有权限,
        return list;
    }

    /**
     * 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
     */
    @Override
    public List getRoleList(Object loginId, String loginType) {
        // 本 list 仅做模拟,实际项目中要根据具体业务逻辑来查询角色
        //        根据用户id从用户角色表中获取角色id
        List roleIds = userRolesService.list(new LambdaQueryWrapper()
                .eq(UserRoles::getUserId,Integer.parseInt(loginId.toString())));
        List list = new ArrayList<>();
        
        if (!(roleIds.size() >0)){
//            用户没有分配角色
            return null;
        }
        roleIds.forEach(roleId ->{
            Roles byId = rolesService.getById(roleId.getRoleId());
            list.add(byId.getName());
        });
//        返回用户所有角色标识集合
        return list;
    }

}

我所实现的是标准的RBAC(基于用户、角色、权限的访问控制模型)。所以,在得到用户id的情况下、先根据用户角色表查出角色id、在根据角色权限表查询权限id,在根据权限表查出具体权限名称。

上面使用了Mybatis-plus的条件构造器和stream流的形式进行查询。

参数解释:

  • loginId:账号id,即你在调用 StpUtil.login(id) 时写入的标识值。
  • loginType:账号体系标识,此处可以暂时忽略,在 [ 多账户认证 ] 章节下会对这个概念做详细的解释。

有同学会产生疑问:我实现了此接口,但是程序启动时好像并没有执行,是不是我写错了? 答:不执行是正常现象,程序启动时不会执行这个接口的方法,在每次调用鉴权代码时,才会执行到此。

权限校验:
然后就可以用以下 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");    

扩展:NotPermissionException 对象可通过 getLoginType() 方法获取具体是哪个 StpLogic 抛出的异常

角色校验:
在 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");        

扩展:NotRoleException 对象可通过 getLoginType() 方法获取具体是哪个 StpLogic 抛出的异常

权限通配符:
Sa-Token允许你根据通配符指定泛权限,例如当一个账号拥有art.*的权限时,art.addart.deleteart.update都将匹配通过

// 当拥有 art.* 权限时
StpUtil.hasPermission("art.add");        // true
StpUtil.hasPermission("art.update");     // true
StpUtil.hasPermission("goods.add");      // false

// 当拥有 *.delete 权限时
StpUtil.hasPermission("art.delete");      // true
StpUtil.hasPermission("user.delete");     // true
StpUtil.hasPermission("user.update");     // false

// 当拥有 *.js 权限时
StpUtil.hasPermission("index.js");        // true
StpUtil.hasPermission("index.css");       // false
StpUtil.hasPermission("index.html");      // false

上帝权限:当一个账号拥有 "*" 权限时,他可以验证通过任何权限码 (角色认证同理)

在我们的项目的TestController中进行测试:
 

  @GetMapping("/hello")
    public String hello() {

        System.out.println("验证权限,是否具有‘所有权限’===============>"+StpUtil.hasPermission("所有权限"));

        System.out.println("验证角色,是否具有‘管理员’角色===============>"+StpUtil.hasRole("管理员"));  
        System.out.println("说hello啊");
        return "test接口的hello";
    }

我们测试的最终结果:
 

springboot整合Sa-Token实现登录认证和权限校验(万字长文)_第5张图片

可以看到确实输出了两个true。并且,只有在每次调用鉴权代码时,才会执行到我们自定义的权限方法中。

总结:

我本来是想写一篇介绍spring boot项目中整合Sa-Token来实现最常用的登录校验和权限认证的,但是写着写着就变成官网的复制机了。我在本篇文章中大量复制了官网上的内容,原本只是想复制一些官方介绍就行了。但是这也从侧面说明了Sa-Token官网制作的确实是比较好的,基本上不需要额外的学习,只要你有做过登录和权限方面的项目经验,再看一遍官网的介绍就能直接上手了。

我之前写过一个B2C模式的购物商台,分为用户端和管理端。管理端的登录和权限校验是用spring security写的。现在又了解了Sa-Token之后,真的还是认为Sa-Token的使用是比较简单的。(也可能是我的项目还是比较简单的,并没有多少权限要实现)并且这也是我们国人写的开源框架,在一些方法的封装、Api的设计上还是能直接理解的。在这里也算是为Sa-Token这个框架打个广告吧,希望大家还是能够多多支持国产,国内的开源之路也是充满了坎坷与艰辛。

你可能感兴趣的:(spring,boot整合第三方技术,spring,boot,Sa-Token,后端)