SaToken鉴权框架

1. 框架介绍

前言:

最新开发文档永远在:https://sa-token.cc

SaToken介绍

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

优点

  • 功能相对Shiro和SpringSecurity更加全面和完整
  • 更加独立,整合项目过程中只需要引入依赖添加配置即可简化了部署的操作
  • API设计简单不冗余复杂。

登录认证体验

// 在登录时写入当前会话的账号id
StpUtil.login(10001);

// 然后在需要校验登录处调用以下方法:
// 如果当前会话未登录,这句代码会抛出 `NotLoginException` 异常
StpUtil.checkLogin();

就上面短短的两句话,我们已经完成了登录认证。

再举两个例子

例如:

权限认证:

(只有具备 user:add 权限的会话才可以进入请求)

@SaCheckPermission("user:add")
@RequestMapping("/user/insert")
public String insert(SysUser user) {
 // ... 
 return "用户增加";
}

又例如

账号登出:

将某个账号踢下线(待到对方再次访问系统时会抛出NotLoginException异常)

// 使账号id为 10001 的会话强制注销登录
StpUtil.logoutByLoginId(10001);

不止以上这些功能,其实在Sa-Token里,绝大多数功能都可以只用一行代码完成,听着很神奇是吧?但事实就是这样:

StpUtil.login(10001);                     // 标记当前会话登录的账号id
StpUtil.getLoginId();                     // 获取当前会话登录的账号id
StpUtil.isLogin();                        // 获取当前会话是否已经登录, 返回true或false
StpUtil.logout();                         // 当前会话注销登录
StpUtil.logoutByLoginId(10001);           // 让账号为10001的会话注销登录(踢人下线)
StpUtil.hasRole("super-admin");           // 查询当前账号是否含有指定角色标识, 返回true或false
StpUtil.hasPermission("user:add");        // 查询当前账号是否含有指定权限, 返回true或false
StpUtil.getSession();                     // 获取当前账号id的Session
StpUtil.getSessionByLoginId(10001);       // 获取账号id为10001的Session
StpUtil.getTokenValueByLoginId(10001);    // 获取账号id为10001的token令牌值
StpUtil.login(10001, "PC");               // 指定设备标识登录,常用于“同端互斥登录”
StpUtil.logoutByLoginId(10001, "PC");     // 指定设备标识进行强制注销 (不同端不受影响)
StpUtil.openSafe(120);                    // 在当前会话开启二级认证,有效期为120秒 
StpUtil.checkSafe();                      // 校验当前会话是否处于二级认证有效期内,校验失败会抛出异常 
StpUtil.switchTo(10044);                  // 将当前会话身份临时切换为其它账号 

功能一览

  • 登录认证 —— 单端登录、多端登录、同端互斥登录、七天内免登录

  • 权限认证 —— 权限认证、角色认证、会话二级认证

  • 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集成包,真正的开箱即用

功能结构图:

sa-token-js

框架认证流程:

图片

2. 在SpringBoot环境集成

2.1 添加依赖

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

<!-- 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.2 设置配置文件

application.yml 风格

############## Sa-Token 配置 ##############
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

2.3 创建启动类

新建主类 SaTokenDemoApplication.java,复制以下代码:

@SpringBootApplication
public class SaTokenDemoApplication {
    public static void main(String[] args) throws JsonProcessingException {
        SpringApplication.run(SaTokenDemoApplication.class, args);
    }
}

2.4 注册拦截器

SpringBoot2.0为例,新建配置类SaTokenConfigure.java

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    // 注册 Sa-Token 拦截器,打开注解式鉴权功能 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注册 Sa-Token 拦截器,打开AOPm注解式鉴权功能 
        registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");    
    }
}

2.5 全局异常拦截

新建配置类GlobalExceptionHandler.java

@RestControllerAdvice
public class GlobalExceptionHandler {
    // 全局异常拦截 
    @ExceptionHandler
    public SaResult handlerException(Exception e) {
        return SaResult.error(e.getMessage());
    }
}

2.6 集成Redis

Sa-Token 提供了扩展接口,你可以轻松将会话数据存储在一些专业的缓存中间件上(比如 Redis), 做到重启数据不丢失。

2.6.1 引入依赖

<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-redis-jackson</artifactId>
    <version>1.37.0</version>
</dependency>

2.6.2 提供一个 Redis 实例化方案

<!-- 提供Redis连接池 -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-pool2</artifactId>
</dependency>

2.6.3 配置文件

spring: 
    # redis配置 
    redis:
        # Redis数据库索引(默认为0)
        database: 1
        # 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

集成Redis后,框架自动保存数据

2.7 权限认证

img

你需要做的就是新建一个类,实现 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:账号体系标识。

2.8 创建一个测试类

@RestController
@RequestMapping("/user/")
public class UserController {

    // 登录接口
    @RequestMapping("doLogin")
    public SaResult doLogin() {
        // 第1步,先登录上 
        StpUtil.login(10001);
        // 第2步,获取 Token  相关参数 
        SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
        // 第3步,返回给前端 
        return SaResult.data(tokenInfo);
    }

    // 登录校验:只有登录之后才能进入该方法 
    @SaCheckLogin        
    @RequestMapping("isLogin")
    public String isLogin() {
        return "当前会话是否登录:" + StpUtil.isLogin();
    }
    
    // 角色校验:必须具有指定角色才能进入该方法 
    @SaCheckRole("super-admin")        
    @RequestMapping("add")
    public String add() {
        return "用户增加";
    }

    // 权限校验:必须具有指定权限才能进入该方法 
    @SaCheckPermission("user-delete")        
    @RequestMapping("delete")
    public String delete() {
        return "用户删除";
    }

    // 二级认证校验:必须二级认证之后才能进入该方法 
    @SaCheckSafe()        
    @RequestMapping("remove")
    public String remove() {
        return "用户注销";
    }

    // Http Basic 校验:只有通过 Basic 认证后才能进入该方法 
    @SaCheckBasic(account = "sa:123456")
    @RequestMapping("inf")
    public String inf() {
        return "用户信息";
    }

    // 校验当前账号是否被封禁 comment 服务,如果已被封禁会抛出异常,无法进入方法 
    @SaCheckDisable("comment")                
    @RequestMapping("send")
    public String send() {
        return "查询用户信息";
    }
    
    // 注解式鉴权:只要具有其中一个权限即可通过校验 
    @RequestMapping("atJurOr")
    @SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)        
    public SaResult atJurOr() {
        return SaResult.data("用户信息");
    } 
    // mode有两种取值:
	// SaMode.AND,标注一组权限,会话必须全部具有才可通过校验。
	// SaMode.OR,标注一组权限,会话只要具有其一即可通过校验。
	
}

注:以上注解都可以加在类上,代表为这个类所有方法进行鉴权;(携带登录Token)

3. 在SpringCloud环境集成

3.1 配置网关服务

3.1.1 引入依赖

请引入此包

<!-- Sa-Token 权限认证(Reactor响应式集成), 在线文档:https://sa-token.cc -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
    <version>1.37.0</version>
</dependency>
<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-redis-jackson</artifactId>
    <version>1.37.0</version>
</dependency>
<!-- 提供Redis连接池 -->
<dependency>    
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-pool2</artifactId>
</dependency>

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

3.1.2 设置配置文件

# Sa-Token配置
sa-token:
  # token名称 (同时也是cookie名称)
  token-name: satoken
  # token有效期,单位秒,-1代表永不过期
  timeout: 2592000
  # token临时有效期 (指定时间内无操作就视为token过期),单位秒
  activity-timeout: -1
  # 是否允许同一账号并发登录 (为false时新登录挤掉旧登录)
  is-concurrent: true
  # 在多人登录同一账号时,是否共用一个token (为false时每次登录新建一个token)
  is-share: false
  # token风格
  token-style: uuid
  # 是否输出操作日志
  is-log: false
  # 是否从cookie中读取token
  is-read-cookie: false
  # 是否从head中读取token
  is-read-head: true

3.1.3 注册全局过滤器

同拦截器一样,为了避免不必要的性能浪费,Sa-Token全局过滤器默认处于关闭状态,若要使用过滤器组件,首先你需要注册它到项目中:

/**
 * [Sa-Token 权限认证] 配置类 
 */
@Configuration
public class SaTokenConfigure {
    
    /**
     * 注册 [Sa-Token全局过滤器] 
     */
    @Bean
    public SaReactorFilter getSaServletFilter() {
        return new SaReactorFilter()
        
                // 指定 拦截路由 与 放行路由
                .addInclude("/**").addExclude("/favicon.ico")    /* 排除掉 /favicon.ico */
                
                // 认证函数: 每次请求执行 
                .setAuth(obj -> {
                    System.out.println("---------- 进入Sa-Token全局认证 -----------");
                    
                    // 登录认证 -- 拦截所有路由,并排除/user/doLogin 用于开放登录 
                    SaRouter.match("/**", "/user/doLogin", r -> StpUtil.checkLogin());

                    // 角色认证 -- 拦截 /user/delete 的路由,必须具备[admin]角色角色才可以通过认证
                    SaRouter.match("/user/delete").check(r -> StpUtil.checkRole("admin"));
                    
                    // 权限认证 -- 不同模块, 校验不同权限
                    SaRouter.match("/user/add", r -> StpUtil.checkPermission("user.add"));
                })
                
                // 异常处理函数:每次认证函数发生异常时执行此函数 
                .setError(e -> {
                    System.out.println("---------- 进入Sa-Token异常处理 -----------");
                    return SaResult.error(e.getMessage());
                })
                
                // 前置函数:在每次认证函数之前执行(BeforeAuth 不受 includeList 与 excludeList 的限制,所有请求都会进入)
                .setBeforeAuth(obj -> {
                    // ---------- 设置跨域响应头 ----------
                    SaHolder.getResponse()
                            // 允许指定域访问跨域资源
                            .setHeader("Access-Control-Allow-Origin", "*")
                            // 允许所有请求方式
                            .setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS, DELETE")
                            // 有效时间
                            .setHeader("Access-Control-Max-Age", "3600")
                            // 允许的header参数
                            .setHeader("Access-Control-Allow-Headers", "*");

                    // 如果是预检请求,则立即返回到前端
                    SaRouter.match(SaHttpMethod.OPTIONS)
                            .free(r -> System.out.println("--------OPTIONS预检请求,不做处理"))
                            .back();
                });
    }
    
}

注意事项:

  • [认证函数]里,你可以写和拦截器里一致的代码,进行路由匹配鉴权,参考:路由拦截鉴权

3.1.4 全局异常拦截

新建配置类GlobalExceptionHandler.java

@RestControllerAdvice
public class GlobalExceptionHandler {
    // 全局异常拦截 
    @ExceptionHandler
    public SaResult handlerException(Exception e) {
        return SaResult.error(e.getMessage());
    }
}

3.1.5 权限认证

你需要做的就是新建一个类,实现 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<>();    
        list.add("101");
        list.add("user.add");
        list.add("user.update");
        list.add("user.get");
        list.add("art.*");
        return list;
    }

    /**
     * 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
     */
    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        // 本 list 仅做模拟,实际项目中要根据具体业务逻辑来查询角色
        List<String> list = new ArrayList<Strin>();    
        list.add("super-admin");
        return list;
    }

}

参数解释:

  • loginId:账号id,即你在调用 StpUtil.login(id) 时写入的标识值。
  • loginType:账号体系标识。

3.2 业务模块

3.2.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>

<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-redis-jackson</artifactId>
    <version>1.37.0</version>
</dependency>

<!-- 提供Redis连接池 -->
<dependency>    
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-pool2</artifactId>
</dependency>

3.2.2 设置配置文件

application.yml 风格

############## Sa-Token 配置 ##############
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.2.3 创建测试类

@RestController
@RequestMapping("/user/")
public class UserController {

    // 登录接口
    @RequestMapping("doLogin")
    public SaResult doLogin() {
        // 第1步,先登录上 
        StpUtil.login(10001);
        // 第2步,获取 Token  相关参数 
        SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
        // 第3步,返回给前端 
        return SaResult.data(tokenInfo);
    }

    @RequestMapping("isLogin")
    public SaResult isLogin() {
        return SaResult.ok("当前会话是否登录:" + StpUtil.isLogin());
    }

    @RequestMapping("add")
    public SaResult add() {
        return SaResult.ok("用户注册");
    }

    @RequestMapping("delete")
    public SaResult delete() {
        return SaResult.ok("用户删除");
    }

}       
  • 28
    点赞
  • 20
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值