注解鉴权 —— 优雅的将鉴权与业务代码分离。本篇我们将介绍在 Sa-Token 中如何通过注解完成权限校验。
Sa-Token 是一个轻量级 java 权限认证框架,主要解决登录认证、权限认证、单点登录、OAuth2、微服务网关鉴权 等一系列权限相关问题。
Gitee 开源地址:https://gitee.com/dromara/sa-token
一、Sa-Token 鉴权注解一览
Sa-Token 为我们提供的鉴权注解包括但不限于以下:
@SaCheckLogin
: 登录校验 —— 只有登录之后才能进入该方法。@SaCheckRole("admin")
: 角色校验 —— 必须具有指定角色标识才能进入该方法。@SaCheckPermission("user:add")
: 权限校验 —— 必须具有指定权限才能进入该方法。@SaCheckSafe
: 二级认证校验 —— 必须二级认证之后才能进入该方法。@SaCheckBasic
: HttpBasic校验 —— 只有通过 Basic 认证后才能进入该方法。@SaCheckDisable("comment")
:账号服务封禁校验 —— 校验当前账号指定服务是否被封禁。@SaIgnore
:忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权。
首先在项目中引入 Sa-Token 依赖:
cn.dev33 sa-token-spring-boot-starter 1.34.0
注:如果你使用的是 SpringBoot 3.x
,只需要将 sa-token-spring-boot-starter
修改为 sa-token-spring-boot3-starter
即可。
二、登录认证
Sa-Token 使用全局拦截器完成注解鉴权功能,为了不为项目带来不必要的性能负担,拦截器默认处于关闭状态
因此,为了使用注解鉴权,你必须手动将 Sa-Token 的全局拦截器注册到你项目中。
以SpringBoot2.0
为例,新建配置类SaTokenConfigure.java
@Configurationpublic class SaTokenConfigure implements WebMvcConfigurer {// 注册 Sa-Token 拦截器,打开注解式鉴权功能 @Overridepublic void addInterceptors(InterceptorRegistry registry) {// 注册 Sa-Token 拦截器,打开注解式鉴权功能 registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");}}
保证此类被springboot
启动类扫描到即可。
新建 LoginController
,添加以下代码:
/** * 登录认证注解测试 */@RestControllerpublic class LoginController { // 访问 home 页,登录后才能访问 ---- http://localhost:8081/home @SaCheckLogin @RequestMapping("home") public SaResult home() { return SaResult.ok("访问成功,此处为登录后才能看到的信息"); } // 登录接口 ---- http://localhost:8081/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/home
返回如下:
{"code": 500,"msg": "未能读取到有效Token","data": null}
会话尚未登录,因此无法访问资源。
现在我们再去访问一下登录接口:
http://localhost:8081/doLogin?name=zhang&pwd=123456
返回如下:
{"code": 200,"msg": "登录成功","data": null}
登录成功,我们再去访问资源接口:
http://localhost:8081/home
返回如下:
{"code": 200,"msg": "访问成功,此处为登录后才能看到的信息","data": null}
通过登录认证校验,成功获取到信息!
三、权限认证 & 角色认证
首先我们需要实现 StpInterface
接口,告诉框架指定账号拥有哪些权限码。
/** * 自定义权限认证接口扩展,Sa-Token 将从此实现类获取每个账号拥有的权限码 * * @author kong * @since 2022-10-13 */@Component// 打开此注解,保证此类被springboot扫描,即可完成sa-token的自定义权限验证扩展 public class StpInterfaceImpl implements StpInterface {/** * 返回一个账号所拥有的权限码集合 */@Overridepublic List getPermissionList(Object loginId, String loginType) {// 本list仅做模拟,实际项目中要根据具体业务逻辑来查询权限List list = new ArrayList();list.add("101");list.add("user.add");list.add("user.update");list.add("user.get");// list.add("user.delete");list.add("art.*");return list;}/** * 返回一个账号所拥有的角色标识集合 */@Overridepublic List getRoleList(Object loginId, String loginType) {// 本list仅做模拟,实际项目中要根据具体业务逻辑来查询角色List list = new ArrayList();list.add("admin");list.add("super-admin");return list;}}
使用以下两个注解完成校验:
@SaCheckPermission("user.add")
:校验当前会话是否具有某个权限。@SaCheckRole("super-admin")
:校验当前会话是否具有某个角色。
/** * Sa-Token 注解鉴权示例 * * @author kong * @since 2022-10-13 */@RestController@RequestMapping("/at-check/")public class AtCheckController {/* * 前提1:首先调用登录接口进行登录 * ---- http://localhost:8081/doLogin?name=zhang&pwd=123456 * * 前提2:项目在配置类中注册拦截器 SaInterceptor ,此拦截器将打开注解鉴权功能 * * 前提3:项目实现了 StpInterface 接口,此接口会告诉框架指定账号拥有哪些权限码 * * 然后我们就可以使用以下示例中的代码进行注解鉴权了 */// 权限校验 ---- http://localhost:8081/at-check/checkPermission//只有具有 user.add 权限的账号才可以进入方法 @SaCheckPermission("user.add")@RequestMapping("checkPermission")public SaResult checkPermission() {// ... return SaResult.ok();}// 角色校验 ---- http://localhost:8081/at-check/checkRole//只有具有 super-admin 角色的账号才可以进入方法 @SaCheckRole("super-admin")@RequestMapping("checkRole")public SaResult checkRole() {// ... return SaResult.ok();}}
可根据代码注释提供的链接进行测试访问。
四、设定校验模式
@SaCheckRole
与@SaCheckPermission
注解可设置校验模式,例如:
// 注解式鉴权:只要具有其中一个权限即可通过校验 @RequestMapping("atJurOr")@SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)public SaResult atJurOr() {return SaResult.data("用户信息");}
mode有两种取值:
SaMode.AND
, 标注一组权限,会话必须全部具有才可通过校验。SaMode.OR
, 标注一组权限,会话只要具有其一即可通过校验。
五、角色权限双重 “or校验”
假设有以下业务场景:一个接口在具有权限 user.add
或角色 admin
时可以调通。怎么写?
// 角色权限双重 “or校验”:具备指定权限或者指定角色即可通过校验@RequestMapping("userAdd")@SaCheckPermission(value = "user.add", orRole = "admin")public SaResult userAdd() {return SaResult.data("用户信息");}
orRole 字段代表权限认证未通过时的次要选择,两者只要其一认证成功即可通过校验,其有三种写法:
- 写法一:
orRole = "admin"
,代表需要拥有角色 admin 。 - 写法二:
orRole = {"admin", "manager", "staff"}
,代表具有三个角色其一即可。 - 写法三:
orRole = {"admin, manager, staff"}
,代表必须同时具有三个角色。
六、二级认证
@RestController@RequestMapping("/at/")public class AtController {// 在当前会话完成二级认证 ---- http://localhost:8081/at/openSafe @RequestMapping("openSafe")public SaResult openSafe() {StpUtil.openSafe(200); // 打开二级认证,有效期为200秒return SaResult.ok();}// 通过二级认证后,才可以进入 ---- http://localhost:8081/at/checkSafe @SaCheckSafe@RequestMapping("checkSafe")public SaResult checkSafe() {return SaResult.ok();}}
必须先经过 StpUtil.openSafe(1200)
打开二级认证(参数为指定认证有效期,单位:秒),才可以通过 @SaCheckSafe 的检查。
七、HttpBasic认证:
@RestController@RequestMapping("/at/")public class AtController {// 通过Basic认证后才可以进入 ---- http://localhost:8081/at/checkBasic @SaCheckBasic(account = "sa:123456")@RequestMapping("checkBasic")public SaResult checkBasic() {return SaResult.ok();}}
当我们访问这个接口时,浏览器会强制弹出一个表单:
当我们输入账号密码后 (sa / 123456)
,才可以继续访问数据:
八、服务禁用性校验
@RestController@RequestMapping("/at/")public class AtController {// 只有当前服务没有禁用 comment 服务时,才能够进入方法 ---- http://localhost:8081/at/comment @SaCheckDisable("comment")@RequestMapping("comment")public SaResult comment() {return SaResult.ok();}}
@SaCheckDisable
注解的作用是检测当前账号是否被禁用了指定服务,如果已被禁用则无法进入指定方法,
在之后的章节我们会详细讲述服务禁用
的相关代码,此处先稍作了解即可。
九、忽略认证
使用 @SaIgnore
可表示一个接口忽略认证:
@SaCheckLogin@RestControllerpublic class TestController {// ... 其它方法 // 此接口加上了 @SaIgnore 可以游客访问 @SaIgnore@RequestMapping("getList")public SaResult getList() {// ... return SaResult.ok(); }}
如上代码表示:TestController
中的所有方法都需要登录后才可以访问,但是 getList
接口可以匿名游客访问。
- @SaIgnore 修饰方法时代表这个方法可以被游客访问,修饰类时代表这个类中的所有接口都可以游客访问。
- @SaIgnore 具有最高优先级,当 @SaIgnore 和其它鉴权注解一起出现时,其它鉴权注解都将被忽略。
- @SaIgnore 同样可以忽略掉 Sa-Token 拦截器中的路由鉴权,在下面的 [路由拦截鉴权] 章节中我们会讲到。
十、在业务逻辑层使用注解鉴权
疑问:我能否将注解写在其它架构层呢,比如业务逻辑层?
使用拦截器模式,只能在Controller层
进行注解鉴权,如需在任意层级使用注解鉴权,可使用 AOP注解鉴权
插件。
cn.dev33 sa-token-spring-aop 1.34.0
集成此插件后,便可以在任意层使用 Sa-Token 的注解鉴权了(例如业务逻辑层),不过需要注意的是:
- 拦截器模式和AOP模式不可同时集成,否则会在
Controller
层发生一个注解校验两次的bug。
参考资料
- Sa-Token 文档:https://sa-token.cc
- Gitee 仓库地址:https://gitee.com/dromara/sa-token
- GitHub 仓库地址:https://github.com/dromara/sa-token