标签：StpUtil 登录账号 Token 校验 token Sa 权限

文章很长，且持续更新，建议收藏起来，慢慢读！疯狂创客圈总目录博客园版 为您奉上珍贵的学习资源：

免费赠送 :《尼恩Java面试宝典》 持续更新+ 史上最全 + 面试必备 2000页+ 面试必备 + 大厂必备 +涨薪必备
免费赠送 :《尼恩技术圣经+高并发系列PDF》 ，帮你实现技术自由，完成职业升级，薪酬猛涨！加尼恩免费领
免费赠送经典图书:《Java高并发核心编程（卷1）加强版》 面试必备 + 大厂必备 +涨薪必备加尼恩免费领
免费赠送经典图书:《Java高并发核心编程（卷2）加强版》 面试必备 + 大厂必备 +涨薪必备加尼恩免费领
免费赠送经典图书:《Java高并发核心编程（卷3）加强版》 面试必备 + 大厂必备 +涨薪必备加尼恩免费领

免费赠送资源宝库： Java 必备百度网盘资源大合集价值>10000元加尼恩领取

史上最牛的权限系统，如何设计？来了一个 Sa-Token学习圣经

尼恩特别说明：尼恩的文章，都会在《技术自由圈》公号发布，并且维护最新版本。如果发现图片不可见，请去《技术自由圈》公号查找

尼恩说在前面

在40岁老架构师尼恩的读者交流群(50+)中，最近有小伙伴拿到了一线互联网企业如得物、阿里、滴滴、极兔、有赞、希音、百度、网易、美团的面试资格，并且拿了很多大厂offer。

其中 SpringCloud 工业级底座，是大家的面试核心，面试重点：

说说：用户权限认证，如何设计？

说说：用户SSO 单点登录，如何设计?

最近有小伙伴在面试高级开发岗位，问到了相关的面试题。

小伙伴没有系统的去梳理和总结，所以支支吾吾的说了几句，面试官不满意，面试挂了。

所以，尼恩给大家做一下系统化、体系化的梳理，联合社群小伙伴，来一个 Sa-Token学习圣经：从入门到精通 Sa-Token学习圣经。

特别说明的是，本文属于尼恩团队从0到1 大实战：穿透 SpringCloud 工业级底座工程(一共包括 15大圣经的 ) 其中之一。

15大圣经，使得大家内力猛增，可以充分展示一下大家雄厚的 “技术肌肉”，让面试官爱到 “不能自已、口水直流”，然后实现”offer直提”。

尼恩团队从0到1 大实战 SpringCloud 工业级底座的知识体系的轮廓如下，详情请点击：15大圣经的介绍：

在这里插入图片描述

工业级脚手架实现的包括的 15大学习圣经，目录如下：

在这里插入图片描述

详情请点击：15大圣经的介绍：

其中，专题1 权限设计以及安全认证相关的两个圣经，具体如下：

SpringSecurity& Auth2.0 学习圣经：从入门到精通 SpringSecurity& Auth2.0
史上最牛的权限系统，如何设计？来了一个 Sa-Token学习圣经

本文，就是 SpringSecurity& Auth2.0 学习圣经的 v1.0版本。这个版本，稍后会录制视频，录完之后，正式版本会有更新，最新版本找尼恩获取。

1 基本概念

安全认证两个基本概念

认证（Authentication）
授权（Authorization）

1.1 认证

认证就是根据用户名密码登录的过程，就是所谓的登录认证
对于一些登录之后才能访问的接口（例如：查询我的账号资料），我们通常的做法是增加一层接口校验：

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

那么，判断会话是否登录的依据是什么？我们先来简单分析一下登录访问流程：

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

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

1.2 授权（鉴权）

所谓权限认证，核心逻辑就是判断一个账号是否拥有指定权限：

有，就让你通过。
没有？那么禁止访问！

深入到底层数据中，就是每个账号都会拥有一组权限码集合，框架来校验这个集合中是否包含指定的权限码。
例如：当前账号拥有权限码集合 ["user-add", "user-delete", "user-get"]，这时候我来校验权限 "user-update"，则其结果就是：验证失败，禁止访问。

2 Sa-Token简介

2.1 介绍

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

Sa-Token 旨在以简单、优雅的方式完成系统的权限认证部分，以登录认证为例，你只需要：

// 会话登录，参数填登录人的账号id 
StpUtil.login(10001);

无需实现任何接口，无需创建任何配置文件，只需要这一句静态代码的调用，便可以完成会话登录认证。
如果一个接口需要登录后才能访问，我们只需调用以下代码：

// 校验当前客户端是否已经登录，如果未登录则抛出 `NotLoginException` 异常
StpUtil.checkLogin();

在 Sa-Token 中，大多数功能都可以一行代码解决：
踢人下线：

// 将账号id为 10077 的会话踢下线 
StpUtil.kickout(10077);

权限认证：

// 注解鉴权：只有具备 `user:add` 权限的会话才可以进入方法
@SaCheckPermission("user:add")
public String insert(SysUser user) {
// ... 
return "用户增加";
}

路由拦截鉴权：

// 根据路由划分模块，不同模块不同鉴权 
registry.addInterceptor(new SaInterceptor(handler -> {
    SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
    SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
    SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
    SaRouter.match("/orders/**", r -> StpUtil.checkPermission("orders"));
    SaRouter.match("/notice/**", r -> StpUtil.checkPermission("notice"));
    // 更多模块... 
})).addPathPatterns("/**");

当你受够 Shiro、SpringSecurity 等框架的三拜九叩之后，你就会明白，相对于这些传统老牌框架，Sa-Token 的 API 设计是多么的简单、优雅！

2.2 功能一览

Sa-Token 目前主要五大功能模块：登录认证、权限认证、单点登录、OAuth2.0、微服务鉴权。

登录认证 —— 单端登录、多端登录、同端互斥登录、七天内免登录。
权限认证 —— 权限认证、角色认证、会话二级认证。
踢人下线 —— 根据账号id踢人下线、根据Token值踢人下线。
注解式鉴权 —— 优雅的将鉴权与业务代码分离。
路由拦截式鉴权 —— 根据路由拦截鉴权，可适配 restful 模式。
Session会话 —— 全端共享Session,单端独享Session,自定义Session,方便的存取值。
持久层扩展 —— 可集成 Redis，重启数据不丢失。
前后台分离 —— APP、小程序等不支持 Cookie 的终端也可以轻松鉴权。
Token风格定制 —— 内置六种 Token 风格，还可：自定义 Token 生成策略。
记住我模式 —— 适配 [记住我] 模式，重启浏览器免验证。
二级认证 —— 在已登录的基础上再次认证，保证安全性。
模拟他人账号 —— 实时操作任意用户状态数据。
临时身份切换 —— 将会话身份临时切换为其它账号。
同端互斥登录 —— 像QQ一样手机电脑同时在线，但是两个手机上互斥登录。
账号封禁 —— 登录封禁、按照业务分类封禁、按照处罚阶梯封禁。
密码加密 —— 提供基础加密算法，可快速 MD5、SHA1、SHA256、AES 加密。
会话查询 —— 提供方便灵活的会话查询接口。
Http Basic认证 —— 一行代码接入 Http Basic、Digest 认证。
全局侦听器 —— 在用户登陆、注销、被踢下线等关键性操作时进行一些AOP操作。
全局过滤器 —— 方便的处理跨域，全局设置安全响应头等操作。
多账号体系认证 —— 一个系统多套账号分开鉴权（比如商城的 User 表和 Admin 表）
单点登录 —— 内置三种单点登录模式：同域、跨域、同Redis、跨Redis、前后端分离等架构都可以搞定。
单点注销 —— 任意子系统内发起注销，即可全端下线。
OAuth2.0认证 —— 轻松搭建 OAuth2.0 服务，支持openid模式。
分布式会话 —— 提供共享数据中心分布式会话方案。
微服务网关鉴权 —— 适配Gateway、ShenYu、Zuul等常见网关的路由拦截认证。
RPC调用鉴权 —— 网关转发鉴权，RPC调用鉴权，让服务调用不再裸奔
临时Token认证 —— 解决短时间的 Token 授权问题。
独立Redis —— 将权限缓存与业务缓存分离。
Quick快速登录认证 —— 为项目零代码注入一个登录页面。
标签方言 —— 提供 Thymeleaf 标签方言集成包，提供 beetl 集成示例。
jwt集成 —— 提供三种模式的 jwt 集成方案，提供 token 扩展参数能力。
RPC调用状态传递 —— 提供 dubbo、grpc 等集成包，在RPC调用时登录状态不丢失。
参数签名 —— 提供跨系统API调用签名校验模块，防参数篡改，防请求重放。
自动续签 —— 提供两种Token过期策略，灵活搭配使用，还可自动续签。
开箱即用 —— 提供SpringMVC、WebFlux、Solon 等常见框架集成包，开箱即用。
最新技术栈 —— 适配最新技术栈：支持 SpringBoot 3.x，jdk 17。

功能结构图：
在这里插入图片描述

3 Sa-Token认证

在这里插入图片描述

spring boot整合sa-token

添加依赖

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

配置文件

# 端口
server:
    port: 8081

# 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.1 登录认证

在这里插入图片描述

登录与注销

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

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

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

你暂时不需要完整了解整个登录过程，你只需要记住关键一点：Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端。
所以一般情况下，我们的登录接口代码，会大致类似如下：

// 会话登录接口 
@RequestMapping("doLogin")
public SaResult doLogin(String name, String pwd) {
    // 第一步：比对前端提交的账号名称、密码
    if("zhang".equals(name) && "123456".equals(pwd)) {
        // 第二步：根据账号id，进行登录 
        StpUtil.login(10001);
        return SaResult.ok("登录成功");
    }
    return SaResult.error("登录失败");
}

如果你对以上代码阅读没有压力，你可能会注意到略显奇怪的一点：此处仅仅做了会话登录，但并没有主动向前端返回 token 信息。是因为不需要吗？严格来讲是需要的，只不过 StpUtil.login(id) 方法利用了 Cookie 自动注入的特性，省略了你手写返回 token 的代码。

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 查询

// 获取当前会话的 token 值
StpUtil.getTokenValue();

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

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

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

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

SaTokenInfo参数详解：

{
    "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"   // 登录设备类型 
    },
}

测试案例

来个小测试加深下理解
新建 LoginController，复制或手动敲出以下代码

/**
 * 登录测试 
 */
@RestController
@RequestMapping("/acc/")
public class LoginController {

    // 测试登录  ---- http://localhost:8081/acc/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/acc/isLogin
    @RequestMapping("isLogin")
    public SaResult isLogin() {
        return SaResult.ok("是否登录：" + StpUtil.isLogin());
    }
    
    // 查询 Token 信息  ---- http://localhost:8081/acc/tokenInfo
    @RequestMapping("tokenInfo")
    public SaResult tokenInfo() {
        return SaResult.data(StpUtil.getTokenInfo());
    }
    
    // 测试注销  ---- http://localhost:8081/acc/logout
    @RequestMapping("logout")
    public SaResult logout() {
        StpUtil.logout();
        return SaResult.ok();
    }
    
}

案例代码：com.pj.controller.LoginAuthController

3.2 踢人下线

所谓踢人下线，核心操作就是找到指定 loginId 对应的 Token，并设置其失效。
在这里插入图片描述

强制注销

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

踢人下线

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

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

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

3.3 全局异常处理

如何根据NotLoginException异常的场景值，来定制化处理未登录的逻辑
应用场景举例：未登录、被顶下线、被踢下线等场景需要不同方式来处理
在会话未登录的情况下尝试获取loginId会使框架抛出NotLoginException异常，而同为未登录异常却有五种抛出场景的区分

场景值	对应常量	含义说明
-1	NotLoginException.NOT_TOKEN	未能从请求中读取到有效 token
-2	NotLoginException.INVALID_TOKEN	已读取到 token，但是 token 无效
-3	NotLoginException.TOKEN_TIMEOUT	已读取到 token，但是 token 已经过期 (详
)
-4	NotLoginException.BE_REPLACED	已读取到 token，但是 token 已被顶下线
-5	NotLoginException.KICK_OUT	已读取到 token，但是 token 已被踢下线
-6	NotLoginException.TOKEN_FREEZE	已读取到 token，但是 token 已被冻结
-7	NotLoginException.NO_PREFIX	未按照指定前缀提交 token

可以使用Spring MVC全局异常处理机制对于未登录场景值处理，那么，如何获取场景值呢？废话少说直接上代码：

// 全局异常拦截（拦截项目中的NotLoginException异常）
@ExceptionHandler(NotLoginException.class)
public SaResult handlerNotLoginException(NotLoginException nle)
        throws Exception {

    // 打印堆栈，以供调试
    nle.printStackTrace(); 
    
    // 判断场景值，定制化异常信息 
    String message = "";
    if(nle.getType().equals(NotLoginException.NOT_TOKEN)) {
        message = "未能读取到有效 token";
    }
    else if(nle.getType().equals(NotLoginException.INVALID_TOKEN)) {
        message = "token 无效";
    }
    else if(nle.getType().equals(NotLoginException.TOKEN_TIMEOUT)) {
        message = "token 已过期";
    }
    else if(nle.getType().equals(NotLoginException.BE_REPLACED)) {
        message = "token 已被顶下线";
    }
    else if(nle.getType().equals(NotLoginException.KICK_OUT)) {
        message = "token 已被踢下线";
    }
    else if(nle.getType().equals(NotLoginException.TOKEN_FREEZE)) {
        message = "token 已被冻结";
    }
    else if(nle.getType().equals(NotLoginException.NO_PREFIX)) {
        message = "未按照指定前缀提交 token";
    }
    else {
        message = "当前会话未登录";
    }
    
    // 返回给前端
    return SaResult.error(message);
}

注意：以上代码并非处理逻辑的最佳方式，只为以最简单的代码演示出场景值的获取与应用，大家可以根据自己的项目需求来定制化处理

3.4 二级认证

在某些敏感操作下，我们需要对已登录的会话进行二次验证。
比如代码托管平台的仓库删除操作，尽管我们已经登录了账号，当我们点击 [删除] 按钮时，还是需要再次输入一遍密码，这么做主要为了两点：

保证操作者是当前账号本人。
增加操作步骤，防止误删除重要数据。

这就是我们本篇要讲的 —— 二级认证，即：在已登录会话的基础上，进行再次验证，提高会话的安全性。

具体API

在Sa-Token中进行二级认证非常简单，只需要使用以下API：

// 在当前会话 开启二级认证，时间为120秒
StpUtil.openSafe(120); 

// 获取：当前会话是否处于二级认证时间内
StpUtil.isSafe(); 

// 检查当前会话是否已通过二级认证，如未通过则抛出异常
StpUtil.checkSafe(); 

// 获取当前会话的二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
StpUtil.getSafeTime(); 

// 在当前会话 结束二级认证
StpUtil.closeSafe();

一个小示例

一个完整的二级认证业务流程，应该大致如下：

// 删除仓库
@RequestMapping("deleteProject")
public SaResult deleteProject(String projectId) {
    // 第1步，先检查当前会话是否已完成二级认证 
    if(!StpUtil.isSafe()) {
        return SaResult.error("仓库删除失败，请完成二级认证后再次访问接口");
    }

    // 第2步，如果已完成二级认证，则开始执行业务逻辑
    // ... 

    // 第3步，返回结果 
    return SaResult.ok("仓库删除成功"); 
}

// 提供密码进行二级认证 
@RequestMapping("openSafe")
public SaResult openSafe(String password) {
    // 比对密码（此处只是举例，真实项目时可拿其它参数进行校验）
    if("123456".equals(password)) {
        
        // 比对成功，为当前会话打开二级认证，有效期为120秒 
        StpUtil.openSafe(120);
        return SaResult.ok("二级认证成功");
    }
    
    // 如果密码校验失败，则二级认证也会失败
    return SaResult.error("二级认证失败"); 
}

调用步骤：

前端调用 deleteProject 接口，尝试删除仓库。
后端校验会话尚未完成二级认证，返回： 仓库删除失败，请完成二级认证后再次访问接口。
前端将信息提示给用户，用户输入密码，调用 openSafe 接口。
后端比对用户输入的密码，完成二级认证，有效期为：120秒。
前端在 120 秒内再次调用 deleteProject 接口，尝试删除仓库。
后端校验会话已完成二级认证，返回：仓库删除成功。

指定业务标识进行二级认证

如果项目有多条业务线都需要敏感操作验证，则 StpUtil.openSafe() 无法提供细粒度的认证操作，此时我们可以指定一个业务标识来分辨不同的业务线：

// 在当前会话 开启二级认证，业务标识为client，时间为600秒
StpUtil.openSafe("client", 600); 

// 获取：当前会话是否已完成指定业务的二级认证 
StpUtil.isSafe("client"); 

// 校验：当前会话是否已完成指定业务的二级认证 ，如未认证则抛出异常
StpUtil.checkSafe("client"); 

// 获取当前会话指定业务二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
StpUtil.getSafeTime("client"); 

// 在当前会话 结束指定业务标识的二级认证
StpUtil.closeSafe("client");

业务标识可以填写任意字符串，不同业务标识之间的认证互不影响，比如：

// 打开了业务标识为 client 的二级认证 
StpUtil.openSafe("client"); 

// 判断是否处于 shop 的二级认证，会返回 false 
StpUtil.isSafe("shop");  // 返回 false 

// 也不会通过校验，会抛出异常 
StpUtil.checkSafe("shop");

使用注解进行二级认证

在一个方法上使用 @SaCheckSafe 注解，可以在代码进入此方法之前进行一次二级认证校验

// 二级认证：必须二级认证之后才能进入该方法 
@SaCheckSafe      
@RequestMapping("add")
public String add() {
    return "用户增加";
}

// 指定业务类型，进行二级认证校验
@SaCheckSafe("art")
@RequestMapping("add2")
public String add2() {
    return "文章增加";
}

实例代码：com.pj.controller.SafeAuthController

3.5 同端互斥登录

如果你经常使用腾讯QQ，就会发现它的登录有如下特点：它可以手机电脑同时在线，但是不能在两个手机上同时登录一个账号。
同端互斥登录，指的就是：像腾讯QQ一样，在同一类型设备上只允许单地点登录，在不同类型设备上允许同时在线。

具体API

在 Sa-Token 中如何做到同端互斥登录?
首先在配置文件中，将 isConcurrent 配置为false，然后调用登录等相关接口时声明设备类型即可：

指定设备类型登录

// 指定`账号id`和`设备类型`进行登录
StpUtil.login(10001, "PC");

调用此方法登录后，同设备的会被顶下线（不同设备不受影响），再次访问系统时会抛出 NotLoginException 异常，场景值=-4

指定设备类型强制注销

// 指定`账号id`和`设备类型`进行强制注销 
StpUtil.logout(10001, "PC");

如果第二个参数填写null或不填，代表将这个账号id所有在线端强制注销，被踢出者再次访问系统时会抛出 NotLoginException 异常，场景值=-2

查询当前登录的设备类型

// 返回当前token的登录设备类型
StpUtil.getLoginDevice();

Id 反查 Token

// 获取指定loginId指定设备类型端的tokenValue 
StpUtil.getTokenValueByLoginId(10001, "APP");

案例代码：com.pj.controller.MutexLoginController

3.6 Http Basic/Digest 认证

3.11.1 HttpBasic认证

Http Basic 是 http 协议中最基础的认证方式，其有两个特点：

简单、易集成。
功能支持度低。

在 Sa-Token 中使用 Http Basic 认证非常简单，只需调用几个简单的方法

启用 Http Basic 认证

首先我们在一个接口中，调用 Http Basic 校验：

@RequestMapping("test3")
public SaResult test3() {
    SaHttpBasicUtil.check("sa:123456");
    // ... 其它代码
    return SaResult.ok();
}

然后我们访问这个接口时，浏览器会强制弹出一个表单：

当我们输入账号密码后 （sa / 123456），才可以继续访问数据：

其它启用方式

// 对当前会话进行 Http Basic 校验，账号密码为 yml 配置的值（例如：sa-token.http-basic=sa:123456）
SaHttpBasicUtil.check();

// 对当前会话进行 Http Basic 校验，账号密码为：`sa / 123456`
SaHttpBasicUtil.check("sa:123456");

// 以注解方式启用 Http Basic 校验
@SaCheckHttpBasic(account = "sa:123456")
@RequestMapping("test3")
public SaResult test3() {
    return SaResult.ok();
}

// 在全局拦截器 或 过滤器中启用 Basic 认证 
@Bean
public SaServletFilter getSaServletFilter() {
    return new SaServletFilter()
    .addInclude("/**").addExclude("/favicon.ico")
    .setAuth(obj -> {
        SaRouter.match("/test/**", () -> SaHttpBasicUtil.check("sa:123456"));
    });
}

URL 认证

除了访问后再输入账号密码外，我们还可以在 URL 中直接拼接账号密码通过 Basic 认证，例如：

http://sa:[email protected]:8081/test/test3

3.11.2 Http Digest 认证

Http Digest 认证是 Http Basic 认证的升级版，Http Digest 在提交请求时不会使用明文方式传输认证信息，而是使用一定的规则加密后提交。不过对于开发者来讲，开启 Http Digest 认证校验的流程与 Http Basic 认证基本是一致的。

// 测试 Http Digest 认证   浏览器访问： http://localhost:8081/test/testDigest
@RequestMapping("testDigest")
public SaResult testDigest() {
    SaHttpDigestUtil.check("sa", "123456");
    return SaResult.ok();
}

// 使用注解方式开启 Http Digest 认证
@SaCheckHttpDigest("sa:123456")
@RequestMapping("testDigest2")
public SaResult testDigest() {
    return SaResult.ok();
}


// 对当前会话进行 Http Digest 校验，账号密码为 yml 配置的值（例如：sa-token.http-digest=sa:123456）
SaHttpDigestUtil.check();

与上面的 Http Basic 认证一致，在访问这个路由时，浏览器会强制弹出一个表单，客户端输入正确的账号密码后即可通过校验。
同样的，Http Digest 也支持在浏览器访问接口时直接使用 @ 符号拼接账号密码信息，使客户端直接通过校验。

http://sa:[email protected]:8081/test/testDigest

4 Sa-Token授权（鉴权）

4.1 权限认证

所谓权限认证，核心逻辑就是判断一个账号是否拥有指定权限：

有，就让你通过。
没有？那么禁止访问！

所以现在问题的核心就是两个：

如何获取一个账号所拥有的权限码集合？
本次操作需要验证的权限码是哪个？

4.1.1 获取当前账号权限码集合

因为每个项目的需求不同，其权限设计也千变万化，因此 [ 获取当前账号权限码集合 ] 这一操作不可能内置到框架中，所以 Sa-Token 将此操作以接口的方式暴露给你，以方便你根据自己的业务逻辑进行重写。
StpInterface类似Spring Security的UserDetailService
你需要做的就是新建一个类，实现 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：账号体系标识，此处可以暂时忽略，在 [ 多账户认证 ] 章节下会对这个概念做详细的解释。

可参考代码：com.pj.satoken.StpInterfaceImpl
有同学会产生疑问：我实现了此接口，但是程序启动时好像并没有执行，是不是我写错了？
答：不执行是正常现象，程序启动时不会执行这个接口的方法，在每次调用鉴权代码时，才会执行到此。

4.1.2 权限校验

然后就可以用以下 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 抛出的异常

4.1.3 角色校验

在 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 抛出的异常

4.1.4 拦截全局异常

有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？当然不可以！
你可以创建一个全局异常拦截器，统一返回给前端的格式，参考：

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

可参考：com.pj.current.GlobalException

4.1.5 权限通配符

Sa-Token允许你根据通配符指定泛权限，例如当一个账号拥有art.*的权限时，art.add、art.delete、art.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

上帝权限：当一个账号拥有 "*" 权限时，他可以验证通过任何权限码（角色认证同理）

4.1.6 如何把权限精确到按钮级？

权限精确到按钮级的意思就是指：权限范围可以控制到页面上的每一个按钮是否显示。
思路：如此精确的范围控制只依赖后端已经难以完成，此时需要前端进行一定的逻辑判断。
如果是前后端一体项目，可以参考：Thymeleaf 标签方言，如果是前后端分离项目，则：

在登录时，把当前账号拥有的所有权限码一次性返回给前端。
前端将权限码集合保存在localStorage或其它全局状态管理对象中。
在需要权限控制的按钮上，使用 js 进行逻辑判断，例如在Vue框架中我们可以使用如下写法：

// `arr`是当前用户拥有的权限码数组
// `user.delete`是显示按钮需要拥有的权限码
// `删除按钮`是用户拥有权限码才可以看到的内容。
<button v-if="arr.indexOf('user.delete') > -1">删除按钮</button>

以上写法只为提供一个参考示例，不同框架有不同写法，大家可根据项目技术栈灵活封装进行调用。

前端有了鉴权后端还需要鉴权吗？
需要！
前端的鉴权只是一个辅助功能，对于专业人员这些限制都是可以轻松绕过的，为保证服务器安全：无论前端是否进行了权限校验，后端接口都需要对会话请求再次进行权限校验！

代码示例：com.pj.controller.JurAuthController

4.2 注解鉴权

有同学表示：尽管使用代码鉴权非常方便，但是我仍希望把鉴权逻辑和业务逻辑分离开来，我可以使用注解鉴权吗？当然可以！

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

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

Sa-Token 使用全局拦截器完成注解鉴权功能，为了不为项目带来不必要的性能负担，拦截器默认处于关闭状态
因此，为了使用注解鉴权，你必须手动将 Sa-Token 的全局拦截器注册到你项目中

4.2.1 注册拦截器

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

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

保证此类被springboot启动类扫描到即可

4.2.2 使用注解鉴权

然后我们就可以愉快的使用注解鉴权了：

// 登录校验：只有登录之后才能进入该方法 
@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 校验：只有通过 Http Basic 认证后才能进入该方法 
@SaCheckHttpBasic(account = "sa:123456")
@RequestMapping("add")
public String add() {
    return "用户增加";
}

// Http Digest 校验：只有通过 Http Digest 认证后才能进入该方法 
@SaCheckHttpDigest(value = "sa:123456")
@RequestMapping("add")
public String add() {
    return "用户增加";
}

// 校验当前账号是否被封禁 comment 服务，如果已被封禁会抛出异常，无法进入方法 
@SaCheckDisable("comment")                
@RequestMapping("send")
public String send() {
    return "查询用户信息";
}

注：以上注解都可以加在类上，代表为这个类所有方法进行鉴权

4.2.3 设定校验模式

@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，标注一组权限，会话只要具有其一即可通过校验。

4.2.4 角色权限双重 “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"}，代表必须同时具有三个角色。

4.2.5 忽略认证

使用 @SaIgnore 可表示一个接口忽略认证：

@SaCheckLogin
@RestController
public class TestController {

    // ... 其它方法 

    // 此接口加上了 @SaIgnore 可以游客访问 
    @SaIgnore
    @RequestMapping("getList")
    public SaResult getList() {
        // ... 
        return SaResult.ok(); 
    }
}

如上代码表示：TestController 中的所有方法都需要登录后才可以访问，但是 getList 接口可以匿名游客访问。

@SaIgnore 修饰方法时代表这个方法可以被游客访问，修饰类时代表这个类中的所有接口都可以游客访问。
@SaIgnore 具有最高优先级，当 @SaIgnore 和其它鉴权注解一起出现时，其它鉴权注解都将被忽略。
@SaIgnore 同样可以忽略掉 Sa-Token 拦截器中的路由鉴权，在下面的 [路由拦截鉴权] 章节中我们会讲到。

4.2.6 批量注解鉴权

使用 @SaCheckOr 表示批量注解鉴权：

// 在 `@SaCheckOr` 中可以指定多个注解，只要当前会话满足其中一个注解即可通过验证，进入方法。
@SaCheckOr(
    login = @SaCheckLogin,
    role = @SaCheckRole("admin"),
    permission = @SaCheckPermission("user.add"),
    safe = @SaCheckSafe("update-password"),
    httpBasic = @SaCheckHttpBasic(account = "sa:123456"),
    disable = @SaCheckDisable("submit-orders")
)
@RequestMapping("test")
public SaResult test() {
    // ... 
    return SaResult.ok(); 
}

每一项属性都可以写成数组形式，例如：

// 当前客户端只要有 [ login 账号登录] 或者 [user 账号登录] 其一，就可以通过验证进入方法。
//         注意：`type = "login"` 和 `type = "user"` 是多账号模式章节的扩展属性，此处你可以先略过这个知识点。
@SaCheckOr(
    login = { @SaCheckLogin(type = "login"), @SaCheckLogin(type = "user") }
)
@RequestMapping("test")
public SaResult test() {
    // ... 
    return SaResult.ok(); 
}

疑问：既然有了 @SaCheckOr，为什么没有与之对应的 @SaCheckAnd 呢？
因为当你写多个注解时，其天然就是 and 校验关系，例如：

// 当你在一个方法上写多个注解鉴权时，其默认就是要满足所有注解规则后，才可以进入方法，只要有一个不满足，就会抛出异常
@SaCheckLogin
@SaCheckRole("admin")
@SaCheckPermission("user.add")
@RequestMapping("test")
public SaResult test() {
    // ... 
    return SaResult.ok(); 
}

代码示例：com.pj.controller.AtCheckController

4.3 路由拦截鉴权

假设我们有如下需求：
需求场景
项目中所有接口均需要登录认证，只有 “登录接口” 本身对外开放
我们怎么实现呢？给每个接口加上鉴权注解？手写全局拦截器？似乎都不是非常方便。
在这个需求中我们真正需要的是一种基于路由拦截的鉴权模式，那么在Sa-Token怎么实现路由拦截鉴权呢？

4.3.1 注册 Sa-Token 路由拦截器

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

@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("/user/doLogin"); 
    }
}

以上代码，我们注册了一个基于 StpUtil.checkLogin() 的登录校验拦截器，并且排除了/user/doLogin接口用来开放登录（除了/user/doLogin以外的所有接口都需要登录才能访问）。

4.3.2 校验函数详解

自定义认证规则：new SaInterceptor(handle -> StpUtil.checkLogin()) 是最简单的写法，代表只进行登录校验功能。
我们可以往构造函数塞一个完整的 lambda 表达式，来定义详细的校验规则，例如：

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注册 Sa-Token 拦截器，定义详细认证规则 
        registry.addInterceptor(new SaInterceptor(handler -> {
            // 指定一条 match 规则
            SaRouter
            .match("/**")    // 拦截的 path 列表，可以写多个 */
            .notMatch("/user/doLogin")        // 排除掉的 path 列表，可以写多个 
            .check(r -> StpUtil.checkLogin());        // 要执行的校验动作，可以写完整的 lambda 表达式

            // 根据路由划分模块，不同模块不同鉴权 
            SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
            SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
            SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
            SaRouter.match("/orders/**", r -> StpUtil.checkPermission("orders"));
            SaRouter.match("/notice/**", r -> StpUtil.checkPermission("notice"));
            SaRouter.match("/comment/**", r -> StpUtil.checkPermission("comment"));
        })).addPathPatterns("/**");
    }
}

SaRouter.match() 匹配函数有两个参数：

参数一：要匹配的path路由。
参数二：要执行的校验函数。

在校验函数内不只可以使用 StpUtil.checkPermission("xxx") 进行权限校验，你还可以写任意代码，例如：

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    // 注册 Sa-Token 的拦截器
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注册路由拦截器，自定义认证规则 
        registry.addInterceptor(new SaInterceptor(handler -> {
            
            // 登录校验 -- 拦截所有路由，并排除/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"));
            SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
            SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
            SaRouter.match("/orders/**", r -> StpUtil.checkPermission("orders"));
            SaRouter.match("/notice/**", r -> StpUtil.checkPermission("notice"));
            SaRouter.match("/comment/**", r -> StpUtil.checkPermission("comment"));
            
            // 甚至你可以随意的写一个打印语句
            SaRouter.match("/**", r -> System.out.println("----啦啦啦----"));

            // 连缀写法
            SaRouter.match("/**").check(r -> System.out.println("----啦啦啦----"));
            
        })).addPathPatterns("/**");
    }
}

4.3.3 匹配特征详解

除了上述示例的 path 路由匹配，还可以根据很多其它特征进行匹配，以下是所有可匹配的特征：

// 基础写法样例：匹配一个path，执行一个校验函数 
SaRouter.match("/user/**").check(r -> StpUtil.checkLogin());

// 根据 path 路由匹配   ——— 支持写多个path，支持写 restful 风格路由 
// 功能说明: 使用 /user , /goods 或者 /art/get 开头的任意路由都将进入 check 方法
SaRouter.match("/user/**", "/goods/**", "/art/get/{id}").check( /* 要执行的校验函数 */ );

// 根据 path 路由排除匹配 
// 功能说明: 使用 .html , .css 或者 .js 结尾的任意路由都将跳过, 不会进入 check 方法
SaRouter.match("/**").notMatch("*.html", "*.css", "*.js").check( /* 要执行的校验函数 */ );

// 根据请求类型匹配 
SaRouter.match(SaHttpMethod.GET).check( /* 要执行的校验函数 */ );

// 根据一个 boolean 条件进行匹配 
SaRouter.match( StpUtil.isLogin() ).check( /* 要执行的校验函数 */ );

// 根据一个返回 boolean 结果的lambda表达式匹配 
SaRouter.match( r -> StpUtil.isLogin() ).check( /* 要执行的校验函数 */ );

// 多个条件一起使用 
// 功能说明: 必须是 Get 请求 并且 请求路径以 `/user/` 开头 
SaRouter.match(SaHttpMethod.GET).match("/user/**").check( /* 要执行的校验函数 */ );

// 可以无限连缀下去 
// 功能说明: 同时满足 Get 方式请求, 且路由以 /admin 开头, 路由中间带有 /send/ 字符串, 路由结尾不能是 .js 和 .css
SaRouter
    .match(SaHttpMethod.GET)
    .match("/admin/**")
    .match("/**/send/**") 
    .notMatch("/**/*.js")
    .notMatch("/**/*.css")
    // ....
    .check( /* 只有上述所有条件都匹配成功，才会执行最后的check校验函数 */ );

4.3.4 提前退出匹配链

使用 SaRouter.stop() 可以提前退出匹配链，例：

registry.addInterceptor(new SaInterceptor(handler -> {
    SaRouter.match("/**").check(r -> System.out.println("进入1"));
    SaRouter.match("/**").check(r -> System.out.println("进入2")).stop();
    SaRouter.match("/**").check(r -> System.out.println("进入3"));
    SaRouter.match("/**").check(r -> System.out.println("进入4"));
    SaRouter.match("/**").check(r -> System.out.println("进入5"));
})).addPathPatterns("/**");

如上示例，代码运行至第2条匹配链时，会在stop函数处提前退出整个匹配函数，从而忽略掉剩余的所有match匹配
除了stop()函数，SaRouter还提供了 back() 函数，用于：停止匹配，结束执行，直接向前端返回结果

// 执行back函数后将停止匹配，也不会进入Controller，而是直接将 back参数 作为返回值输出到前端
SaRouter.match("/user/back").back("要返回到前端的内容");复制到剪贴板错误复制成功

1
2

stop() 与 back() 函数的区别在于：

SaRouter.stop() 会停止匹配，进入Controller。
SaRouter.back() 会停止匹配，直接返回结果到前端。

4.3.5 使用free打开一个独立的作用域

// 进入 free 独立作用域 
SaRouter.match("/**").free(r -> {
    SaRouter.match("/a/**").check(/* --- */);
    SaRouter.match("/b/**").check(/* --- */).stop();
    SaRouter.match("/c/**").check(/* --- */);
});
// 执行 stop() 函数跳出 free 后继续执行下面的 match 匹配 
SaRouter.match("/**").check(/* --- */);

free() 的作用是：打开一个独立的作用域，使内部的 stop() 不再一次性跳出整个 Auth 函数，而是仅仅跳出当前 free 作用域。

4.3.6 使用注解忽略掉路由拦截校验

我们可以使用 @SaIgnore 注解，忽略掉路由拦截认证：
1、先配置好了拦截规则：

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new SaInterceptor(handler -> {
        // 根据路由划分模块，不同模块不同鉴权 
        SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
        SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
        SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
        // ... 
    })).addPathPatterns("/**");
}

2、然后在 Controller 里又添加了忽略校验的注解

@SaIgnore
@RequestMapping("/user/getList")
public SaResult getList() {
    System.out.println("------------ 访问进来方法"); 
    return SaResult.ok(); 
}

请求将会跳过拦截器的校验，直接进入 Controller 的方法中。

注解 **@SaIgnore** 的忽略效果只针对 SaInterceptor拦截器和 AOP注解鉴权生效，对自定义拦截器与过滤器不生效。

4.3.7 关闭注解校验

SaInterceptor 只要注册到项目中，默认就会打开注解校验，如果要关闭此能力，需要：

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(
        new SaInterceptor(handle -> {
            SaRouter.match("/**").check(r -> StpUtil.checkLogin());
        }).isAnnotation(false)  // 指定关闭掉注解鉴权能力，这样框架就只会做路由拦截校验了 
    ).addPathPatterns("/**");
}

实例代码：com.pj.satoken.SaTokenConfigure

拦截器和过滤器鉴权：
首先我们先梳理清楚一个问题，既然拦截器已经可以实现路由鉴权，为什么还要用过滤器再实现一遍呢？简而言之：

相比于拦截器，过滤器更加底层，执行时机更靠前，有利于防渗透扫描。

过滤器可以拦截静态资源，方便我们做一些权限控制。

部分Web框架根本就没有提供拦截器功能，但几乎所有的Web框架都会提供过滤器机制。

但是过滤器也有一些缺点，比如：

由于太过底层，导致无法率先拿到HandlerMethod对象，无法据此添加一些额外功能。

由于拦截的太全面了，导致我们需要对很多特殊路由(如/favicon.ico)做一些额外处理。

在Spring中，过滤器中抛出的异常无法进入全局@ExceptionHandler，我们必须额外编写代码进行异常处理。

Sa-Token同时提供过滤器和拦截器机制，不是为了让谁替代谁，而是为了让大家根据自己的实际业务合理选择，拥有更多的发挥空间。

5 Sa-Token 进阶

5.1 Session会话

Session 是数据缓存组件，通过 Session 我们可以很方便的缓存一些高频读写数据，提高程序性能。

提起Session，你脑海中最先浮现的可能就是 JSP 中的 HttpSession，它的工作原理可以大致总结为：
客户端每次与服务器第一次握手时，会被强制分配一个 [唯一id] 作为身份标识，注入到 Cookie 之中，之后每次发起请求时，客户端都要将它提交到后台，服务器根据 [唯一id] 找到每个请求专属的Session对象，维持会话
这种机制简单粗暴，却有N多明显的缺点：

同一账号分别在PC、APP登录，会被识别为两个不相干的会话
一个设备难以同时登录两个账号
每次一个新的客户端访问服务器时，都会产生一个新的Session对象，即使这个客户端只访问了一次页面
在不支持Cookie的客户端下，这种机制会失效

Sa-Token Session可以理解为 HttpSession 的升级版：

Sa-Token只在调用StpUtil.login(id)登录会话时才会产生Session，不会为每个陌生会话都产生Session，节省性能
在登录时产生的Session，是分配给账号id的，而不是分配给指定客户端的，也就是说在PC、APP上登录的同一账号所得到的Session也是同一个，所以两端可以非常轻松的同步数据
Sa-Token支持Cookie、Header、body三个途径提交Token，而不是仅限于Cookie
由于不强依赖Cookie，所以只要将Token存储到不同的地方，便可以做到一个客户端同时登录多个账号

5.1.1 Session模型结构图

三种Session创建时机：

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

假设三个客户端登录同一账号，且配置了不共享token，那么此时的Session模型是：

简而言之：

Account-Session 以账号 id 为主，只要 token 指向的账号 id 一致，那么对应的Session对象就一致
Token-Session 以token为主，只要token不同，那么对应的Session对象就不同
Custom-Session 以特定的key为主，不同key对应不同的Session对象，同样的key指向同一个Session对

5.1.2 Account-Session

这种为账号id分配的Session，我们给它起一个合适的名字：Account-Session，你可以通过如下方式操作它：

// 获取当前会话的 Account-Session 
SaSession session = StpUtil.getSession();

// 从 Account-Session 中读取、写入数据 
session.get("name");
session.set("name", "张三");

使用Account-Session在不同端同步数据是非常方便的，因为只要 PC 和 APP 登录的账号id一致，它们对应的都是同一个Session，举个应用场景：在PC端点赞的帖子列表，在APP端的点赞记录里也要同步显示出来

5.1.3 Token-Session

随着业务推进，我们还可能会遇到一些需要数据隔离的场景：
业务场景
指定客户端超过两小时无操作就自动下线，如果两小时内有操作，就再续期两小时，直到新的两小时无操作
那么这种请求访问记录应该存储在哪里呢？放在 Account-Session 里吗？
可别忘了，PC端和APP端可是共享的同一个 Account-Session ，如果把数据放在这里，那就意味着，即使用户在PC端一直无操作，只要手机上用户还在不间断的操作，那PC端也不会过期！
解决这个问题的关键在于，虽然两个设备登录的是同一账号，但是两个它们得到的token是不一样的， Sa-Token针对会话登录，不仅为账号id分配了Account-Session，同时还为每个token分配了不同的Token-Session
不同的设备端，哪怕登录了同一账号，只要它们得到的token不一致，它们对应的 Token-Session 就不一致，这就为我们不同端的独立数据读写提供了支持：

// 获取当前会话的 Token-Session 
SaSession session = StpUtil.getTokenSession();

// 从 Token-Session 中读取、写入数据 
session.get("name");
session.set("name", "张三");

5.1.4 Custom-Session

除了以上两种Session，Sa-Token还提供了第三种Session，那就是：Custom-Session，你可以将其理解为：自定义Session
Custom-Session不依赖特定的账号id 或者 token，而是依赖于你提供的SessionId：

// 获取指定key的 Custom-Session 
SaSession session = SaSessionCustomUtil.getSessionById("goods-10001");

// 从 Custom-Session 中读取、写入数据 
session.get("name");
session.set("name", "张三");

只要两个自定义Session的Id一致，它们就是同一个Session
Custom-Session的会话有效期默认使用SaManager.getConfig().getTimeout(), 如果需要修改会话有效期, 可以在创建之后, 使用对象方法修改

session.updateTimeout(1000); // 参数说明和全局有效期保持一致复制到剪贴板错误复制成功

1

5.1.5 未登录场景下获取 Token-Session

默认场景下，只有登录后才能通过 StpUtil.getTokenSession() 获取 Token-Session。
如果想要在未登录场景下获取 Token-Session ，有两种方法：

方法一：将全局配置项 tokenSessionCheckLogin 改为 false，详见：框架配置
方法二：使用匿名 Token-Session

// 获取当前 Token 的匿名 Token-Session （可在未登录情况下使用的 Token-Session）
StpUtil.getAnonTokenSession();

注意点：如果前端没有提交 Token ，或者提交的 Token 是一个无效 Token 的话，框架将不会根据此 Token 创建 Token-Session 对象，而是随机一个新的 Token 值来创建 Token-Session 对象，此 Token 值可以通过 StpUtil.getTokenValue() 获取到。

5.2 身份切换

以上介绍的 API 都是操作当前账号，对当前账号进行各种鉴权操作，你可能会问，我能不能对别的账号进行一些操作？
比如：查看账号 10001 有无某个权限码、获取账号 id=10002 的 Account-Session，等等...
Sa-Token 在 API 设计时充分考虑了这一点，暴露出多个api进行此类操作：

有关操作其它账号的api

// 获取指定账号10001的`tokenValue`值 
StpUtil.getTokenValueByLoginId(10001);

// 将账号10001的会话注销登录
StpUtil.logout(10001);

// 获取账号10001的Session对象, 如果session尚未创建, 则新建并返回
StpUtil.getSessionByLoginId(10001);

// 获取账号10001的Session对象, 如果session尚未创建, 则返回null 
StpUtil.getSessionByLoginId(10001, false);

// 获取账号10001是否含有指定角色标识 
StpUtil.hasRole(10001, "super-admin");

// 获取账号10001是否含有指定权限码
StpUtil.hasPermission(10001, "user:add");

临时身份切换

有时候，我们需要直接将当前会话的身份切换为其它账号，比如：

// 将当前会话[身份临时切换]为其它账号（本次请求内有效）
StpUtil.switchTo(10044);

// 此时再调用此方法会返回 10044 (我们临时切换到的账号id)
StpUtil.getLoginId();

// 结束 [身份临时切换]
StpUtil.endSwitch();

你还可以：直接在一个代码段里方法内，临时切换身份为指定loginId（此方式无需手动调用StpUtil.endSwitch()关闭身份切换）

System.out.println("------- [身份临时切换]调用开始...");
StpUtil.switchTo(10044, () -> {
    System.out.println("是否正在身份临时切换中: " + StpUtil.isSwitch());  // 输出 true
    System.out.println("获取当前登录账号id: " + StpUtil.getLoginId());   // 输出 10044
});
System.out.println("------- [身份临时切换]调用结束...");

实例代码：com.pj.controller.SwitchToController

5.3 [记住我] 模式

如图所示，一般网站的登录界面都会有一个 [记住我] 按钮，当你勾选它登录后，即使你关闭浏览器再次打开网站，也依然会处于登录状态，无须重复验证密码：

那么在Sa-Token中，如何做到 [ 记住我 ] 功能呢？

在 Sa-Token 中实现记住我功能

Sa-Token的登录授权，默认就是[记住我]模式，为了实现[非记住我]模式，你需要在登录时如下设置：

// 设置登录账号id为10001，第二个参数指定是否为[记住我]，当此值为false后，关闭浏览器后再次打开需要重新登录
StpUtil.login(10001, false);

那么，Sa-Token实现[记住我]的具体原理是？

实现原理

Cookie作为浏览器提供的默认会话跟踪机制，其生命周期有两种形式，分别是：

临时Cookie：有效期为本次会话，只要关闭浏览器窗口，Cookie就会消失。
持久Cookie：有效期为一个具体的时间，在时间未到期之前，即使用户关闭了浏览器Cookie也不会消失。

利用Cookie的此特性，我们便可以轻松实现 [记住我] 模式：

勾选 [记住我] 按钮时：调用StpUtil.login(10001, true)，在浏览器写入一个持久Cookie储存 Token，此时用户即使重启浏览器 Token 依然有效。
不勾选 [记住我] 按钮时：调用StpUtil.login(10001, false)，在浏览器写入一个临时Cookie储存 Token，此时用户在重启浏览器后 Token 便会消失，导致会话失效。

前后端分离模式下如何实现[记住我]?

此时机智的你

标签：StpUtil,登录,账号,Token,校验,token,Sa,权限
From： https://www.cnblogs.com/crazymakercircle/p/18376997

史上最牛的 权限系统，如何设计？ 来了一个 Sa-Token学习圣经

史上最牛的 权限系统，如何设计？ 来了一个 Sa-Token学习圣经

尼恩说在前面

1 基本概念

1.1 认证

1.2 授权（鉴权）

2 Sa-Token简介

2.1 介绍

2.2 功能一览

3 Sa-Token认证

3.1 登录认证

3.2 踢人下线

3.3 全局异常处理

3.4 二级认证

3.5 同端互斥登录

3.6 Http Basic/Digest 认证

3.11.1 HttpBasic认证

3.11.2 Http Digest 认证

4 Sa-Token授权（鉴权）

4.1 权限认证

4.1.1 获取当前账号权限码集合

4.1.2 权限校验

4.1.3 角色校验

4.1.4 拦截全局异常

4.1.5 权限通配符

4.1.6 如何把权限精确到按钮级？

4.2 注解鉴权

4.2.1 注册拦截器

4.2.2 使用注解鉴权

4.2.3 设定校验模式

4.2.4 角色权限双重 “or校验”

4.2.5 忽略认证

4.2.6 批量注解鉴权

4.3 路由拦截鉴权

4.3.1 注册 Sa-Token 路由拦截器

4.3.2 校验函数详解

4.3.3 匹配特征详解

4.3.4 提前退出匹配链

4.3.5 使用free打开一个独立的作用域

4.3.6 使用注解忽略掉路由拦截校验

4.3.7 关闭注解校验

5 Sa-Token 进阶

5.1 Session会话

5.1.1 Session模型结构图

5.1.2 Account-Session

5.1.3 Token-Session

5.1.4 Custom-Session

5.1.5 未登录场景下获取 Token-Session

5.2 身份切换

5.3 [记住我] 模式

相关文章

赞助商

阅读排行

史上最牛的权限系统，如何设计？来了一个 Sa-Token学习圣经

史上最牛的权限系统，如何设计？来了一个 Sa-Token学习圣经