Sa-Token 是一个轻量级 Java 权限认证框架，其核心设计围绕登录认证、权限校验、Session 会话和单点登录展开，对 Spring Boot 的集成非常友好。与 Spring Security 相比，Sa-Token 的配置更少，API 更贴近业务语义，通过 StpUtil 工具类即可完成大部分操作。框架内部采用策略模式管理不同的认证实现，默认基于内存存储会话，同时支持 Redis 等持久化扩展，在保持轻量的同时具备生产环境所需的能力。
对于需要快速搭建权限体系的 Spring Boot 项目，Sa-Token 可以显著降低学习成本和集成成本。接下来将从核心机制、基础配置、注解鉴权和单点登录四个部分展开，帮助开发者掌握完整的整合思路。
一、Sa-Token 核心机制与轻量级设计
Sa-Token 将登录状态抽象为 LoginId，通常对应业务系统中的用户主键。调用 StpUtil.login(1001) 后，框架会在当前请求上下文中写入登录态，并根据配置生成一个 token 返回给客户端。后续请求只需要携带该 token，框架就能通过拦截器或过滤器自动解析并恢复登录上下文。整个过程无需手动维护 Session，也不依赖传统的 HttpSession 机制，因此可以轻松扩展到无状态服务或微服务网关场景。
权限控制方面，Sa-Token 提供了基于角色的模型和基于权限码的模型。角色模型适合粗粒度控制，例如判断用户是否具备 admin 角色；权限码模型则更精细，例如 order:add 表示新增订单的权限。框架支持在配置类中集中定义拦截规则，也支持在控制器方法上使用注解。两种方式可以结合使用，拦截器负责全局登录校验，注解负责细粒度权限校验，职责清晰且直观。
Sa-Token 的轻量体现在两个方面：一是核心包体积小，没有引入过多传递依赖；二是 API 设计非常直白，StpUtil.login、StpUtil.logout、StpUtil.checkLogin、StpUtil.checkPermission 等方法名称与业务含义一一对应。对于中小型项目而言，这意味着不需要编写大量样板代码，也不需要理解复杂的过滤器链和认证管理器，就能获得完整的认证与授权能力。
二、Spring Boot 整合 Sa-Token 的基础配置
整合的第一步是在 Maven 或 Gradle 项目中引入 Sa-Token 的 Spring Boot Starter。该 Starter 会自动装配核心组件，包括上下文处理器、拦截器注册入口和配置属性绑定。引入依赖后，只需要在 application.yml 中添加少量配置并编写一个配置类，即可完成基础集成。
以下依赖以 Maven 为例，版本可以根据实际情况选择稳定版本。建议使用与 Spring Boot 版本兼容的最新版，避免出现 API 不匹配的问题。
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.34.0</version>
</dependency>
在 application.yml 中通常需要配置 token 名称、有效期、是否允许并发登录以及 token 生成风格。这些参数会直接影响客户端携带凭证的方式和会话失效策略。例如 token-name 设置为 satoken 时，客户端需要通过 satoken 请求头或参数传递凭证。timeout 单位为秒，设置 -1 表示永不过期，适合需要长期登录的桌面端应用。
sa-token: token-name: satoken timeout: 2592000 active-timeout: -1 is-concurrent: true is-share: true token-style: uuid is-log: false
接下来需要注册一个全局拦截器，让 Sa-Token 能够拦截请求并执行登录校验。在 Spring Boot 中实现 WebMvcConfigurer 接口并添加拦截器即可。下面的配置类对除登录、登出和 SSO 相关路径外的所有请求执行 StpUtil.checkLogin()，未登录时框架会抛出 NotLoginException，可以通过全局异常处理器转换为统一的 JSON 响应。
@Configuration
public class SaTokenConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new SaInterceptor(handle -> StpUtil.checkLogin()))
.addPathPatterns("/**")
.excludePathPatterns("/user/login", "/user/logout", "/sso/*");
}
}
SaInterceptor 的构造参数是一个 SaParamFunction 接口，这里使用 Lambda 表达式传入登录校验逻辑。如果不需要全局登录校验，也可以只注册拦截器而不执行任何逻辑，然后完全依赖注解进行权限控制。这种灵活的拦截方式允许开发者根据项目的实际安全边界来定制拦截范围，避免过度校验导致的接口访问异常。
三、基于注解的权限认证实践
Sa-Token 提供了一组开箱即用的注解，包括 @SaCheckLogin、@SaCheckPermission、@SaCheckRole 和 @SaCheckSafe。这些注解可以标注在控制器类或方法上，框架通过 AOP 在方法执行前完成校验。注解方式适合细粒度权限控制，与全局拦截器形成互补。例如全局拦截器只校验登录态，而具体接口再通过 @SaCheckPermission 校验是否拥有某个权限码。
下面先实现一个简单的登录接口，用户提交用户名和密码后，如果账号密码正确，就调用 StpUtil.login 写入登录态。登录成功后，客户端会收到一个 token，后续访问受保护接口时携带该 token 即可完成认证。实际项目中密码必须加密存储，这里为了演示直接使用明文比较。
@RestController
public class UserController {
@PostMapping("/user/login")
public SaResult login(String username, String password) {
if ("admin".equals(username) && "123456".equals(password)) {
StpUtil.login(1001);
return SaResult.ok("登录成功");
}
return SaResult.error("账号或密码错误");
}
@GetMapping("/user/info")
public SaResult info() {
Object loginId = StpUtil.getLoginId();
return SaResult.data(loginId);
}
}
在业务控制器中，可以直接给方法添加权限注解。下面的订单控制器中，list 接口只需要登录即可访问，add 接口需要 order:add 权限，delete 接口则需要 admin 角色。当权限校验失败时，框架会抛出 NotPermissionException 或 NotRoleException，同样可以通过全局异常处理器返回友好的错误提示。
@RestController
@RequestMapping("/order")
public class OrderController {
@SaCheckLogin
@GetMapping("/list")
public SaResult list() {
return SaResult.ok("订单列表");
}
@SaCheckPermission("order:add")
@PostMapping("/add")
public SaResult add() {
return SaResult.ok("新增订单");
}
@SaCheckRole("admin")
@DeleteMapping("/delete")
public SaResult delete() {
return SaResult.ok("删除订单");
}
}
注解校验的底层实现基于 SaStrategy 策略与 AOP 切面，性能开销很小，不会对接口响应时间产生明显影响。需要注意的是，注解中传入的权限码或角色名必须与业务系统定义一致，否则会导致校验不通过。如果权限体系较为复杂，建议在项目中统一维护权限码常量，避免出现拼写错误和重复定义。
除了注解，Sa-Token 还支持在配置类中定义路由拦截规则，通过 SaRouteFunction 接口返回一组 SaRouteItem 对象，每个对象包含路由匹配表达式和所需权限。这种方式适合需要在网关层或统一入口做集中式鉴权的场景，可以避免在大量控制器方法上重复添加注解。但它的可读性略低于注解方式，通常需要结合项目团队的习惯来选择。
四、单点登录模式配置与跨域登录流程
Sa-Token 提供了 SSO 模块，可以将一个服务作为认证中心，其他子系统作为客户端接入。认证中心的职责是处理登录表单、校验账号密码、签发 ticket 并重定向回客户端；客户端的职责是接收 ticket，然后向认证中心发起校验请求，获取用户信息并建立本地会话。整个流程基于 ticket 一次性凭证，安全性高于直接传递 token，适合多系统统一登录的场景。
在认证中心服务中，需要引入 sa-token-sso 模块并注册服务端处理器。服务端处理器负责暴露 SSO 相关的接口，例如登录页、ticket 签发和校验接口。下面是一个简单的服务端配置类，通过 @Bean 创建 SaSsoServerProcessor 即可启用服务端能力。
@Configuration
public class SaSsoServerConfig {
@Bean
public SaSsoServerProcessor saSsoServerProcessor() {
return new SaSsoServerProcessor();
}
}
客户端服务则需要注册客户端处理器，并配置认证中心地址、客户端回调地址以及 ticket 校验方式。客户端处理器会自动处理回调请求和本地会话创建。通常客户端还需要配置一个拦截器，对未登录请求跳转到认证中心的登录页，并携带 redirect 参数指定登录成功后的回跳地址。这样可以实现一次登录，多个客户端子系统共享登录状态。
@Configuration
public class SaSsoClientConfig {
@Bean
public SaSsoClientProcessor saSsoClientProcessor() {
return new SaSsoClientProcessor();
}
}
在 application.yml 中，认证中心和客户端分别需要配置 sso 相关的参数。认证中心需要设置 ticket 有效期和是否允许 http 传输；客户端需要设置认证中心域名、自身回调地址和 sso 接口前缀。由于单点登录涉及跨域跳转，正式环境中务必使用 https 并配置好 Cookie 的 SameSite 属性，避免浏览器限制导致 session 无法共享。Sa-Token 内部对跨域处理提供了基础支持，但复杂场景下仍建议通过网关统一处理 CORS 和域名映射。
单点登录的登录流程通常如下：用户访问客户端受保护页面，客户端拦截器发现未登录，重定向到认证中心的登录页并带上 redirect 地址；用户在认证中心完成登录后，认证中心生成 ticket 并重定向回客户端的回调地址；客户端回调处理器收到 ticket，调用认证中心校验接口，校验成功后创建本地会话并重定向到最初访问的页面。整个过程中 ticket 只能使用一次，有效期为几分钟，极大降低了凭证泄露的风险。
Sa-Token 的 SSO 模式还支持多种扩展，例如跨域单点登录、与第三方 OAuth2 协议对接、以及多端登录互踢。对于需要集成现有用户体系的团队，可以通过自定义 SaSsoServerTemplate 来扩展认证中心的账号校验逻辑，而无需修改框架核心代码。这种设计让 Sa-Token 在保持轻量的同时，能够适应大多数企业级单点登录需求。
综上所述，Sa-Token 在 Spring Boot 项目中的整合成本低，权限模型清晰，SSO 能力完整。相比传统的 Spring Security 配置，它更适合中小型项目或希望快速落地的开发场景。只要掌握 StpUtil 工具类、拦截器配置、注解鉴权和 SSO 模块四个关键部分，就可以构建出安全可靠的认证与权限体系。
Spring BootSa-Token权限认证修改时间：2026-10-03 15:02:04