Back to Details

sa-token-micro

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sa-Token 微服务鉴权

Sa-Token Microservice Authentication

基于 
sa-token-doc/micro/
全部 4 个文档。基础认证使用 
sa-token
技能。
Based on all 4 documents in 
sa-token-doc/micro/
. Use the 
sa-token
skill for basic authentication.

Capability Boundaries

Capability Boundaries

✅ Strong Suits

✅ Strong Fits

  1. Same-Token机制 — 内部服务外网隔离，防止绕过网关直接访问子服务
  2. 网关统一鉴权 — SpringCloud Gateway集中式登录+权限校验
  3. Reactor/WebFlux集成 — 响应式框架适配（SaReactorFilter）
  4. 分布式Session — 基于Redis的分布式会话共享
  5. Feign内部调用鉴权 — RPC调用时携带Same-Token
  6. Dubbo/gRPC集成 — 跨服务上下文传播
  7. Same-Token定时刷新 — 支持新旧Token双轨并行
  1. Same-Token mechanism — Isolates internal services from the public network and prevents direct access to child services by bypassing the Gateway
  2. Centralized Gateway authentication — Centralized login and permission validation with SpringCloud Gateway
  3. Reactor/WebFlux integration — Adaptive integration with reactive frameworks (SaReactorFilter)
  4. Distributed Session — Distributed session sharing based on Redis
  5. Feign internal call authentication — Carries the Same-Token during RPC calls
  6. Dubbo/gRPC integration — Propagates context across services
  7. Scheduled Same-Token refresh — Supports concurrent operation of new and old Tokens

⚠️ Requirements

⚠️ Requirements

  1. 所有服务需要共享同一个Redis（Same-Token依赖Redis）
  2. Gateway需要使用Reactor响应式依赖
  3. 子服务需要独立的Sa-Token依赖
  1. All services must share the same Redis instance (Same-Token depends on Redis)
  2. The Gateway must use Reactor reactive dependencies
  3. Each child service needs its own Sa-Token dependency

❌ Out of Scope

❌ Out of Scope

  1. 基础登录/权限/注解鉴权 → sa-token
  2. SSO单点登录 → sa-token-sso
  3. OAuth2.0 → sa-token-oauth2
  4. 单体应用 → 直接使用 sa-token 即可
  1. Basic login/permission/annotation-based authentication → sa-token
  2. SSO single sign-on → sa-token-sso
  3. OAuth2.0 → sa-token-oauth2
  4. Monolithic applications → Use sa-token directly

架构

Architecture

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

工作流

Workflow

Step 1. 引入依赖 — Gateway用Reactor依赖，子服务用Servlet依赖 Step 2. 配置Redis — 所有服务连接到同一个Redis Step 3. Gateway统一鉴权 — SaReactorFilter集中校验登录和权限 Step 4. Gateway注入Same-Token — ForwardAuthFilter添加请求头 Step 5. 子服务校验 — SaServletFilter校验Same-Token Step 6. Feign/Dubbo集成 — RPC调用传递Same-Token Step 7. 定时刷新 — 定期刷新Same-Token以保证高可用
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

文件说明来源
gateway-auth.md网关统一鉴权+分布式Sessiongateway-auth、dcs-session
same-token.mdSame-Token隔离+依赖引入same-token(277行)、import-intro
FileDescriptionSource
gateway-auth.mdCentralized Gateway authentication + distributed Sessiongateway-auth、dcs-session
same-token.mdSame-Token isolation + dependency setupsame-token(277 lines)、import-intro

FAQ

FAQ

Q: Same-Token和OAuth2有什么区别？ A: Same-Token用于同源系统内部鉴权，简单高效。OAuth2用于开放平台第三方授权。内部用Same-Token，外部用OAuth2。
Q: Same-Token有效期多久？ A: 默认86400秒（1天），建议使用定时任务每5分钟刷新一次。刷新时旧Token作为次级Token保留，新旧其一都可通过。
Q: Gateway和子服务需要不同的依赖？ A: 是的。Gateway用 
sa-token-reactor-spring-boot-starter
（响应式），子服务用 
sa-token-spring-boot-starter
（Servlet）。
Q: 分布式Session怎么实现？ A: 只需引入 
sa-token-redis-template
依赖并配置公共Redis地址，框架自动将会话数据存储到Redis，所有服务共享。
Q: Gateway鉴权和子服务鉴权怎么分工？ A: Gateway做统一登录校验+权限校验，子服务做Same-Token校验防止绕过网关直接访问。
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

Gotchas

  1. Gateway必须用Reactor依赖 — 用错Servlet依赖会报错
  2. 所有服务必须连同一个Redis — Same-Token依赖Redis共享
  3. Same-Token默认一天有效期 — 生产环境必须配置定时任务刷新
  4. Feign拦截器需要添加到FeignClient配置中 — 别忘了 
    configuration = FeignInterceptor.class
  5. SaReactorFilter和SaServletFilter不可混用 — Gateway用Reactor，子服务用Servlet
  6. 子服务直接暴露在外网时必须配置Same-Token校验 — 否则可绕过网关直接访问
  7. Same-Token刷新时有短暂的双Token并行期 — 旧Token会被保留直到下次刷新
  8. 分布式Session的数据是序列化后存储的 — 存储的对象必须实现序列化接口
  1. The Gateway must use Reactor dependencies — Using the wrong Servlet dependency causes an error
  2. All services must connect to the same Redis instance — Same-Token depends on shared Redis
  3. Same-Token has a default validity period of one day — A scheduled refresh task must be configured in production environments
  4. The Feign interceptor must be added to the FeignClient configuration — Do not forget 
    configuration = FeignInterceptor.class
  5. SaReactorFilter and SaServletFilter cannot be mixed — Use Reactor for the Gateway and Servlet for child services
  6. 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
  7. There is a brief dual-Token period during a Same-Token refresh — The old Token is retained until the next refresh
  8. Distributed Session data is stored after serialization — Stored objects must implement a serialization interface

Data Privacy

Data Privacy

本技能不收集、存储或传输任何用户数据。所有代码示例仅供本地开发参考。
This skill does not collect, store, or transmit any user data. All code examples are provided for local development reference only.