sa-token-micro

Original：🇨🇳 Chinese

Translated

Sa-Token microservice authentication skill. Covers the Same-Token mechanism for isolating internal services from the public network, centralized authentication through SpringCloud Gateway (Reactor reactive), authentication for internal RPC calls via Feign/Dubbo/gRPC, distributed session solutions (Redis Session center/JWT stateless), Reactor/WebFlux framework integration, and SpringBoot 3/4 dependency compatibility. Use this skill when users need inter-service authentication in a microservice architecture, gateway Token forwarding and validation, isolation of internal services from the public network, or distributed session sharing. For basic login authentication, use the `sa-token` skill first.

9installs

Sourcefull-stack-skills/java-skills

Added on2026-10-18

NPX Install

npx skill4agent add full-stack-skills/java-skills sa-token-micro

SKILL.md Content (Chinese)

View Translation Comparison →

Sa-Token Microservice Authentication

Based on all 4 documents in

sa-token-doc/micro/

. Use the

sa-token

skill for basic authentication.

Capability Boundaries

✅ Strong Fits

Same-Token mechanism — Isolates internal services from the public network and prevents direct access to child services by bypassing the Gateway
Centralized Gateway authentication — Centralized login and permission validation with SpringCloud Gateway
Reactor/WebFlux integration — Adaptive integration with reactive frameworks (SaReactorFilter)
Distributed Session — Distributed session sharing based on Redis
Feign internal call authentication — Carries the Same-Token during RPC calls
Dubbo/gRPC integration — Propagates context across services
Scheduled Same-Token refresh — Supports concurrent operation of new and old Tokens

⚠️ Requirements

All services must share the same Redis instance (Same-Token depends on Redis)
The Gateway must use Reactor reactive dependencies
Each child service needs its own Sa-Token dependency

❌ Out of Scope

Basic login/permission/annotation-based authentication → sa-token
SSO single sign-on → sa-token-sso
OAuth2.0 → sa-token-oauth2
Monolithic applications → Use sa-token directly

Architecture

客户端 → Gateway(校验登录+注入Same-Token) → 子服务(校验Same-Token)
                                                 ↕ Feign(携带Same-Token)
                                              其他子服务(校验Same-Token)

Workflow

Step 1. Add dependencies — Use Reactor dependencies for the Gateway and Servlet dependencies for child services Step 2. Configure Redis — Connect all services to the same Redis instance Step 3. Centralize Gateway authentication — Use SaReactorFilter for centralized login and permission validation Step 4. Inject the Same-Token in the Gateway — ForwardAuthFilter adds the request header Step 5. Validate in child services — SaServletFilter validates the Same-Token Step 6. Integrate Feign/Dubbo — Pass the Same-Token during RPC calls Step 7. Schedule refreshes — Refresh the Same-Token periodically to ensure high availability

Reference Documents

File	Description	Source
gateway-auth.md	Centralized Gateway authentication + distributed Session	gateway-auth、dcs-session
same-token.md	Same-Token isolation + dependency setup	same-token(277 lines)、import-intro

FAQ

Q: How does Same-Token differ from OAuth2? A: Same-Token is used for internal authentication within the same source system and is simple and efficient. OAuth2 is used for third-party authorization on open platforms. Use Same-Token internally and OAuth2 externally.

Q: How long is the Same-Token valid? A: The default is 86,400 seconds (1 day). It is recommended to refresh it every 5 minutes using a scheduled task. During refresh, the old Token is retained as a secondary Token, and either the old or new Token can pass validation.

Q: Do the Gateway and child services require different dependencies? A: Yes. The Gateway uses

sa-token-reactor-spring-boot-starter

(reactive), while child services use

sa-token-spring-boot-starter

(Servlet).

Q: How is a distributed Session implemented? A: Add the

sa-token-redis-template

dependency and configure the shared Redis address. The framework automatically stores Session data in Redis so that all services can share it.

Q: How are responsibilities divided between Gateway authentication and child service authentication? A: The Gateway performs centralized login and permission validation, while child services validate the Same-Token to prevent direct access that bypasses the Gateway.

Gotchas

The Gateway must use Reactor dependencies — Using the wrong Servlet dependency causes an error
All services must connect to the same Redis instance — Same-Token depends on shared Redis
Same-Token has a default validity period of one day — A scheduled refresh task must be configured in production environments
The Feign interceptor must be added to the FeignClient configuration — Do not forget
```
configuration = FeignInterceptor.class
```
SaReactorFilter and SaServletFilter cannot be mixed — Use Reactor for the Gateway and Servlet for child services
Same-Token validation must be configured when a child service is directly exposed to the public internet — Otherwise, users can bypass the Gateway and access the service directly
There is a brief dual-Token period during a Same-Token refresh — The old Token is retained until the next refresh
Distributed Session data is stored after serialization — Stored objects must implement a serialization interface

Data Privacy

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