Sa-Token Integration Extensions
Based on the integration documentation in
.
Applicable Scenarios
Activate this skill when the user needs any of the following:
- JWT stateless authentication — Encode login information into the Token to reduce Redis queries, making it suitable for high-concurrency scenarios
- Distributed Session sharing — Share session data across multiple instances in a distributed deployment
- Redis cache isolation — Physically separate Sa-Token Redis data from the business Redis data
- Service-layer annotation-based authorization — Use annotations such as @SaCheckLogin at the Service layer instead of the Controller layer
- Rapid login page development — Build a zero-code login page for development environments or internal administration systems
- Template engine authorization tags — Control button visibility in Thymeleaf/Freemarker pages
Workflow
Step 1. Identify integration requirements — Select the JWT, Redis, AOP, template, or other required modules
Step 2. Add dependencies — Add the corresponding Maven/Gradle dependencies
Step 3. Configure parameters — Configure jwt-secret-key, Redis connections, Alone-Redis, and other settings
Step 4. Wire up implementations — Inject StpLogic, register filters, and configure the template engine
Step 5. Verify the integration — Confirm that the integration is effective and test whether the core functionality works correctly
Capability Boundaries
✅ Strong Suits
- JWT integration — Choose among the Simple, Mixin, and Stateless modes
- Redis persistence — Use either JDK serialization or JSON serialization
- Alone-Redis standalone Redis — Physically isolate authentication and business caches
- AOP annotation-based authorization — Use annotations such as @SaCheckLogin at the Service layer
- SpEL expressions — Use Spring expressions with @SaCheckEL
- Quick-Login rapid login — Inject a zero-code login page
- JSON serialization extensions — Jackson/Fastjson/Fastjson2/Snack3/Snack4
- Template engine integration — Custom tags for Thymeleaf/Freemarker
- RPC integration — Context propagation for Dubbo/Dubbo3/gRPC
⚠️ Requirements
- JWT requires the configuration
- Redis requires the connection information
- AOP annotations and interceptor annotations cannot be used together
❌ Out of Scope
- Basic login, permissions, and annotation-based authorization → sa-token
- SSO → sa-token-sso
- OAuth2.0 → sa-token-oauth2
- Microservice authentication and authorization → sa-token-micro
Reference Documentation
| Topic | File | Source |
|---|
| Three JWT modes (Simple/Mixin/Stateless) | references/jwt-extend.md | GitHub |
| Redis persistence and Alone-Redis | references/dao-extend.md | dao-extend, integ-redis |
FAQ
Q: How do I choose among the three JWT modes?
A: The Simple mode is recommended because it provides a complete feature set, including force logout, banning, and session management. Choose Stateless when true stateless operation is required, although force logout and banning are unavailable. Mixin falls between the two.
Q: Which Redis serialization method should I use?
A: RedisTemplate-based JSON serialization is recommended because the data is human-readable and easier to troubleshoot. JDK serialization offers better compatibility, but the data is not human-readable.
Q: What is the difference between Alone-Redis and regular Redis?
A: Alone-Redis uses an independent Redis connection and database that is completely isolated from the business Redis, ensuring that business traffic does not affect the authentication cache.
Q: Can AOP annotation-based authorization and interceptor-based authorization be used together?
A: No. AOP is intended for the Service layer, while interceptors are intended for the Controller layer. Choose one approach.
Q: Is Quick-Login suitable for production environments?
A: It is suitable for small systems or internal administration systems. For production environments, a custom login page is recommended.
Q: What functions are supported by the template engine tags?
A: Tags such as
for login verification,
for role checks, and
for permission checks are supported.
Gotchas
- is always false in Simple mode — It is incompatible with Extra data, and tokens cannot be shared
- must be true in Mixin mode — Otherwise, the force-logout API is unavailable
- Tokens use the JWT format after JWT integration — They are no longer UUID-formatted, and their contents can be decoded and viewed
- Alone-Redis uses the independent configuration prefix — It does not use
- Session data is readable in Redis after JSON serialization — It can be viewed directly in a Redis client
- AOP annotations and interceptor annotations cannot be mixed — Choosing AOP means interceptor-based annotations cannot also be used
- The default Quick-Login credentials are sa/123456 — They must be changed in production environments
- Dubbo integration automatically handles context propagation — No additional code is required; simply add the dependency
Data Privacy
This skill does not collect, store, or transmit any user data. All code examples are provided for local development reference only.