Sa-Token — Lightweight Java Authentication and Authorization Framework

Introduction

Sa-Token is a Java authentication and authorization framework that favors simplicity over configuration. A single line of code can log in a user, check roles, issue tokens, or enforce route-level permissions, making it a popular choice for Spring Boot projects needing fast auth integration.

What Sa-Token Does

• Handles login, logout, token issuance, and session management in one API
• Provides annotation-based and programmatic role and permission checks
• Supports Single Sign-On (SSO) across multiple applications
• Includes an OAuth 2.0 server module for third-party authorization
• Integrates with Spring Cloud Gateway for microservice-level auth

Architecture Overview

Sa-Token stores session data in an in-memory concurrent map by default and can switch to Redis for distributed deployments. It intercepts requests through a servlet filter or Spring interceptor, resolves tokens from cookies or headers, and evaluates permission rules before the controller executes. The modular design lets developers pick only the features they need.

Self-Hosting & Configuration

• Add the Spring Boot starter and optionally the Redis plugin
• Configure token name, timeout, and style in application.yml
• Use sa-token.token-style to choose uuid, simple, random, or tik style tokens
• For SSO, deploy the sa-token-sso module and configure ticket exchange endpoints
• Gateway integration requires the sa-token-reactor-spring-boot3-starter

Key Features

• One-line login/logout with automatic token management
• Fine-grained permission system supporting wildcard patterns
• Built-in temporary token and second-level authentication (step-up auth)
• Route-based interceptor for declarative endpoint protection
• Multi-account system support for independent auth domains in one app

Comparison with Similar Tools

• Spring Security — comprehensive but complex; Sa-Token offers a simpler API for common auth scenarios
• Apache Shiro — similar scope; Sa-Token has a more modern API and active maintenance
• Keycloak — full identity provider; Sa-Token is an in-app library, not a standalone server
• Auth.js — JavaScript ecosystem; Sa-Token targets the Java/Spring ecosystem

FAQ

Q: Can Sa-Token replace Spring Security? A: For many applications, yes. Sa-Token covers login, RBAC, SSO, and OAuth 2.0 with a simpler learning curve. Complex LDAP or SAML integrations may still favor Spring Security.

Q: How does it handle distributed sessions? A: Add the sa-token-redis plugin; sessions and tokens are stored in Redis automatically.

Q: Does it work with Spring WebFlux? A: Yes. A reactive starter is provided for WebFlux and Spring Cloud Gateway.

Q: Is the token stateless like JWT? A: By default tokens are stateful (server-side sessions). A JWT integration module is available for stateless tokens.

Sources

• https://github.com/dromara/Sa-Token
• https://sa-token.cc