sa-token-integration

Sa-Token Integration Extension

Based on sa-token-doc/plugin/ integration class documentation.

Applicable Scenarios

Activate this skill when the user needs the following scenarios:

• JWT stateless authentication — Encode login information into the Token, reducing Redis queries, suitable for high-concurrency scenarios
• Distributed Session sharing — Session data needs to be shared during multi-instance deployment
• Redis cache isolation — Physically separate Sa-Token's Redis from the business Redis
• Service-layer annotation authentication — Use annotations such as @SaCheckLogin at the Service layer (not Controller)
• Quickly build a login page — Zero-code login page for development environments or internal management systems
• Template engine authentication tags — Control button visibility in Thymeleaf/Freemarker pages

Workflow

Step 1. Determine integration requirements — Choose JWT/Redis/AOP/template and other modules Step 2. Introduce dependencies — Add the corresponding Maven/Gradle dependencies Step 3. Configure parameters — Configure jwt-secret-key/Redis connection/Alone-Redis, etc. Step 4. Inject implementations — Inject StpLogic, register filters, configure template engine Step 5. Verify and test — Confirm the integration takes effect, and test whether core functions work properly

Capability Boundaries

✅ Strong Suits

1. JWT integration — Choose among the three modes Simple/Mixin/Stateless
2. Redis persistence — Two approaches: JDK serialization/JSON serialization
3. Alone-Redis standalone Redis — Physical isolation of authentication cache and business cache
4. AOP annotation authentication — Use annotations such as @SaCheckLogin at the Service layer
5. SpEL expressions — @SaCheckEL uses Spring expressions
6. Quick-Login quick login — Zero-code injection of the login page
7. JSON serialization extension — Jackson/Fastjson/Fastjson2/Snack3/Snack4
8. Template engine integration — Thymeleaf/Freemarker custom tags
9. RPC integration — Dubbo/Dubbo3/gRPC context propagation

⚠️ Requirements

1. JWT requires configuring jwt-secret-key
2. Redis requires configuring spring.redis connection information
3. AOP annotations and interceptor annotations cannot be used at the same time

❌ Out of Scope

1. Basic login/permission/annotation authentication → sa-token
2. SSO → sa-token-sso
3. OAuth2.0 → sa-token-oauth2
4. Microservice authentication → sa-token-micro

Reference documentation

Topic	File	Source
JWT three modes (Simple/Mixin/Stateless)	references/jwt-extend.md	GitHub
Redis persistence + Alone-Redis	references/dao-extend.md	dao-extend、integ-redis

FAQ

Q: How do you choose among the three JWT modes? A: Simple mode is recommended (complete functionality: kick-out, ban, and session management are all supported). If statelessness is needed, choose Stateless (but kick-out/ban are unavailable). Mixin is between the two.

Q: Which of the two Redis serialization methods should be chosen? A: RedisTemplate JSON serialization is recommended (data is readable, convenient for troubleshooting). JDK serialization has better compatibility but the data is garbled.

Q: What is the difference between Alone-Redis and regular Redis? A: Alone-Redis uses an independent Redis connection and database, fully isolated from business Redis, ensuring that authentication cache is not affected by business.

Q: Can AOP annotation authentication and interceptor authentication be used at the same time? A: They cannot be used at the same time. AOP is used for the Service layer, and interceptors are used for the Controller layer. Choose one.

Q: Is Quick-Login suitable for production environments? A: It is suitable for small systems or internal management systems. For production environments, it is recommended to customize the login page.

Q: What functions do template engine tags support? A: Supports sa:login(login verification),sa:hasRole(role judgment),sa:hasPermission(permission judgment), and other tags.

Gotchas

1. Simple mode is-share is always false — incompatible with Extra data, cannot share token
2. Mixin mode is-concurrent must be true — otherwise the kick-out API is unavailable
3. After JWT integration, Token becomes JWT format — it is no longer uuid format, and the content can be decoded and viewed
4. Alone-Redis has an independent configuration prefix sa-token-alone-redis — not spring.redis
5. After Redis JSON serialization, Session data is readable in Redis — it can be viewed directly in the Redis client
6. AOP annotations and interceptor annotations cannot be mixed — if AOP is chosen, interceptors can no longer be used
7. Quick-Login default account password is sa/123456 — be sure to change it in production environments
8. Dubbo integration automatically handles context propagation — no additional code is needed, just import the dependency

Data Privacy

This skill does not collect, store, or transmit any user data. All code examples are for local development reference only.