sa-token-micro

Sa-Token Microservice Authentication

Based on sa-token-doc/micro/ All 4 documents. Basic authentication uses the sa-token skill.

Capability Boundaries

✅ Strong Suits

1. Same-Token Mechanism — Internal service external-network isolation, preventing direct access to sub-services bypassing the gateway
2. Gateway Unified Authentication — SpringCloud Gateway centralized login + permission verification
3. Reactor/WebFlux Integration — Reactive framework adaptation (SaReactorFilter)
4. Distributed Session — Redis-based distributed session sharing
5. Feign Internal Call Authentication — Carrying Same-Token during RPC calls
6. Dubbo/gRPC Integration — Cross-service context propagation
7. Same-Token Scheduled Refresh — Supports parallel operation of old and new Tokens

⚠️ Requirements

1. All services need to share the same Redis (Same-Token depends on Redis)
2. Gateway needs to use Reactor reactive dependencies
3. Sub-services need independent Sa-Token dependencies

❌ Out of Scope

1. Basic login/permission/annotation authentication → sa-token
2. SSO single sign-on → sa-token-sso
3. OAuth2.0 → sa-token-oauth2
4. Monolithic application → Directly use sa-token is sufficient

Architecture

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

Workflow

Step 1. Introduce dependencies — Gateway uses Reactor dependencies, sub-services use Servlet dependencies Step 2. Configure Redis — All services connect to the same Redis Step 3. Gateway unified authentication — SaReactorFilter centrally verifies login and permissions Step 4. Gateway injects Same-Token — ForwardAuthFilter adds request header Step 5. Sub-service verification — SaServletFilter verifies Same-Token Step 6. Feign/Dubbo integration — RPC calls pass Same-Token Step 7. Scheduled refresh — Periodically refresh Same-Token to ensure high availability

Reference Documents

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

FAQ

Q: What is the difference between Same-Token and OAuth2? A: Same-Token is used for internal authentication within the same-origin system, 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 86400 seconds (1 day). It is recommended to use a scheduled task to refresh every 5 minutes. During refresh, the old Token is retained as a secondary Token, and either the old or new one can pass.

Q: Do Gateway and sub-services need different dependencies? A: Yes. Gateway uses sa-token-reactor-spring-boot-starter(reactive), sub-services use sa-token-spring-boot-starter（Servlet）。

Q: How is distributed Session implemented? A: Just introduce the sa-token-redis-template dependency and configure the public Redis address. The framework automatically stores session data in Redis, shared by all services.

Q: How do Gateway authentication and sub-service authentication divide responsibilities? A: The Gateway performs unified login verification + permission verification, and sub-services perform Same-Token verification to prevent bypassing the gateway for direct access.

Gotchas

1. The Gateway must use the Reactor dependency — using the wrong Servlet dependency will cause errors
2. All services must connect to the same Redis — Same-Token relies on Redis sharing
3. Same-Token has a default validity period of one day — in a production environment, a scheduled task must be configured to refresh it
4. The Feign interceptor needs to be added to the FeignClient configuration — don't forget configuration = FeignInterceptor.class
5. SaReactorFilter and SaServletFilter must not be mixed — the Gateway uses Reactor, sub-services use Servlet
6. When a sub-service is directly exposed to the public network, Same-Token verification must be configured — otherwise it can be accessed directly by bypassing the gateway
7. During Same-Token refresh, there is a brief period of dual-token parallelism — the old Token is retained until the next refresh
8. Distributed Session data is stored after serialization — the stored objects must implement the serialization interface

Data Privacy

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