身份认证与应用安全 / 系统课时
强制指定账号下线
强制指定账号下线
后台封禁账号、重置密码或发现异常登录时,不能等待用户主动退出,而要由管理端立即终止指定账号的现有登录状态。Sa-Token 提供 StpUtil.kickout(loginId) 完成账号级强制下线,并让旧凭证在后续请求中失去正常登录资格。
学习目标
- 使用账号标识调用
StpUtil.kickout(loginId)执行强制下线 - 区分用户主动
logout与后台强制kickout的使用边界 - 按“执行操作、复用旧 Token、确认被拒绝”的顺序验证踢人结果
强制下线解决什么问题
logout() 适合当前用户主动结束自己的登录,而后台处置需要从另一个已授权的请求中操作目标账号。例如风控系统发现账号异常,管理员希望用户已经打开的页面和保存的旧 Token 都不能继续代表该账号访问受保护资源。
此时可以调用 StpUtil.kickout(loginId)。loginId 必须使用系统登录时传给 Sa-Token 的同一种账号标识,例如用户 ID,而不是昵称、手机号展示值或前端临时编号。

调用 kickout
下面示例提供一个后台接口,根据路径中的账号 ID 执行强制下线。它依赖已有 Spring Boot 与 Sa-Token 集成,并假设管理接口已经由项目现有的管理员认证和权限机制保护,因此属于片段示例。
package com.example.admin;
import cn.dev33.satoken.stp.StpUtil;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@RestController
@RequestMapping("/admin/users")
public class UserSessionAdminController {
@PostMapping("/{loginId}/kickout")
public Map<String, Object> kickout(@PathVariable String loginId) {
// loginId 必须与业务登录时使用的账号标识保持一致。
StpUtil.kickout(loginId);
return Map.of("ok", true, "loginId", loginId);
}
}例如要强制账号 <ID> 下线,可以调用:
curl -X POST "http://localhost:<PORT>/admin/users/<ID>/kickout" \
-H "satoken: <ADMIN_TOKEN>"<PORT>、<ID> 和 <ADMIN_TOKEN> 分别替换为实际端口、目标账号标识和有权执行该操作的管理员 Token。
预期输出
{"loginId":"<ID>","ok":true}这里的成功响应只能说明管理接口已经执行了踢人调用。真正的验收还要从目标用户一侧验证旧 Token 是否还能通过登录校验。
用旧 Token 验证结果
保留目标用户被踢之前使用的 Token,再请求一个已经执行 Sa-Token 登录校验的受保护接口。正确结果应是该请求无法继续以原账号的正常登录身份访问业务数据,并进入项目配置的未登录或强制下线处理流程。
不要把“踢人接口返回 200”当作唯一证据。如果传错了 loginId、测试时复用了另一个账号的 Token,或者受测接口本身没有执行登录校验,都可能造成误判。
在启用了多端登录、设备标识或自定义登录类型的系统里,还要先确定业务目标究竟是“让该账号全部现有登录失效”,还是只处理某个终端。需要只影响特定设备时,应按照项目实际采用的 Sa-Token 多端策略选择对应能力,而不要直接把账号级强制下线当成所有场景的默认方案。
把踢人接口当作高权限操作
强制下线会直接影响其他用户的会话,因此管理接口必须先验证操作者身份和权限,并记录必要的操作审计信息。常见记录包括操作者、目标账号、原因以及操作时间,便于封禁、密码重置或安全事件之后追溯。
前端收到被强制下线后的认证失败时,也应清理旧 Token 并跳转登录页,而不是无限重试原请求。这样后台的一次处置才能真正切断旧会话,并让客户端及时回到可恢复的登录流程。