Sa-Token: A Lightweight Java Authentication and Authorization Framework

When building login and authorization features, the author first considered Spring Boot + Spring Security and Spring Boot + Shiro, but both were too heavyweight for a lightweight project, leading to the discovery of Sa-Token.

Sa-Token Overview

Sa-Token is a lightweight Java permission authentication framework that addresses login authentication, permission authentication, single sign‑on, OAuth2.0, distributed sessions, micro‑service gateway authentication, and many other security concerns.

Login Authentication

The typical login flow involves the client sending a username and password, the server validating them, and issuing a token (stored in a cookie) that is automatically sent with subsequent requests. Sa-Token simplifies this to a single call:

StpUtil.login(Object id);

Additional helper methods include logout, login status checks, and token queries:

StpUtil.logout();
StpUtil.isLogin();
StpUtil.checkLogin();
StpUtil.getLoginId();
StpUtil.getTokenValue();
StpUtil.getTokenInfo();

Permission Authentication

Permission checks determine whether the current account possesses a specific permission code. Permissions are retrieved via a custom implementation of StpInterface :

@Component
public class StpInterfaceImpl implements StpInterface {
    @Override
    public List
getPermissionList(Object loginId, String loginType) {
        List
list = new ArrayList<>();
        list.add("101");
        list.add("user-add");
        list.add("user-delete");
        // ... other permissions
        return list;
    }
    @Override
    public List
getRoleList(Object loginId, String loginType) {
        List
list = new ArrayList<>();
        list.add("admin");
        list.add("super-admin");
        return list;
    }
}

Common permission APIs:

StpUtil.getPermissionList();
StpUtil.hasPermission("user-update");
StpUtil.checkPermission("user-update");
StpUtil.checkPermissionAnd("user-update", "user-delete");
StpUtil.checkPermissionOr("user-update", "user-delete");

Role Authentication

Roles can be checked independently of permissions:

StpUtil.getRoleList();
StpUtil.hasRole("super-admin");
StpUtil.checkRole("super-admin");
StpUtil.checkRoleAnd("super-admin", "shop-admin");
StpUtil.checkRoleOr("super-admin", "shop-admin");

Global Exception Handling

A global exception interceptor can convert authentication failures into a unified response format:

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler
    public SaResult handlerException(Exception e) {
        e.printStackTrace();
        return SaResult.error(e.getMessage());
    }
}

Feature Overview

Sa-Token provides a comprehensive set of capabilities, including multi‑device login, session sharing, user kick‑out, account banning, Redis integration, distributed sessions, micro‑service gateway authentication, SSO, OAuth2.0, two‑factor authentication, password encryption, global listeners, and ready‑to‑use starters for Spring MVC, WebFlux, and other frameworks.

Getting Started with Spring Boot

Add the Maven or Gradle dependency cn.dev33:sa-token-spring-boot-starter:1.30.0 , configure application.yml (token name, timeout, concurrency, etc.), and create a main class to launch the application.

Example controller demonstrates login, login‑status query, token info retrieval, and logout using Sa‑Token APIs.

WebFlux Integration

For reactive applications, include sa-token-reactor-spring-boot-starter and register a global SaReactorFilter to handle authentication and error handling across all routes.

Conclusion

Sa-Token is a lightweight yet powerful authentication and authorization framework that simplifies security implementation in Java backend projects.