新增Sa-Id模块，解决微服务内部调用鉴权问题

2026-02-27 16:50:24 +08:00 · 2021-07-24 01:10:46 +08:00
parent bffdd0f2e1
commit 64beb7a18a
12 changed files with 767 additions and 16 deletions
--- a/sa-token-doc/doc/micro/dcs-session.md
+++ b/sa-token-doc/doc/micro/dcs-session.md
@@ -0,0 +1,52 @@
+# 微服务 - 分布式Session会话
+
+--- 
+
+### 需求场景 
+
+微服务架构下的第一个难题便是数据同步，单机版的`Session`在分布式环境下一般不能正常工作，为此我们需要对框架做一些特定的处理。
+
+首先我们要明白，分布式环境下为什么`Session`会失效？因为用户在一个节点对会话做出的更改无法实时同步到其它的节点，
+这就导致一个很严重的问题：如果用户在节点一上已经登录成功，那么当下一次的请求落在节点二上时，对节点二来讲，此用户仍然是未登录状态。
+
+### 解决方案 
+
+要怎么解决这个问题呢？目前的主流方案有四种：
+1. **Session同步**：只要一个节点的数据发生了改变，就强制同步到其它所有节点 
+2. **Session粘滞**：通过一定的算法，保证一个用户的所有请求都稳定的落在一个节点之上，对这个用户来讲，就好像还是在访问一个单机版的服务
+3. **建立会话中心**：将Session存储在专业的缓存中间件上，使每个节点都变成了无状态服务，例如：`Redis`
+4. **颁发无状态token**：放弃Session机制，将用户数据直接写入到令牌本身上，使会话数据做到令牌自解释，例如：`jwt`
+
+
+### 方案选择
+
+该如何选择一个合适的方案？
+- 方案一：性能消耗太大，不太考虑
+- 方案二：需要从网关处动手，与框架无关
+- 方案三：Sa-Token 整合`Redis`非常简单，详见章节：[集成 Redis](/up/integ-redis)
+- 方案四：详见官方仓库中 Sa-Token 整合`jwt`的示例
+
+由于`jwt`模式不在服务端存储数据，对于比较复杂的业务可能会功能受限，因此更加推荐使用方案三
+
+``` xml
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+详细参考：[集成 Redis](/up/integ-redis)
+
+
+
+
+
+
+
+
+
--- a/sa-token-doc/doc/micro/gateway-auth.md
+++ b/sa-token-doc/doc/micro/gateway-auth.md
@@ -0,0 +1,112 @@
+# 微服务 - 网关统一鉴权
+
+微服务架构下的鉴权一般分为两种：
+1. 每个服务各自鉴权
+2. 网关统一鉴权 
+
+方案一和传统单体鉴权差别不大，不再过多赘述，本篇介绍方案二的整合步骤：
+
+--- 
+
+
+
+### 1、引入依赖 
+
+首先，根据 [依赖引入说明](/micro/import-intro) 引入正确的依赖，以`[SpringCloud Gateway]`为例：
+
+``` xml
+<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+注：Redis包是必须的，因为我们需要和各个服务通过Redis来同步数据 
+
+### 2、实现鉴权接口
+``` java
+/**
+ * 自定义权限验证接口扩展 
+ */
+@Component   
+public class StpInterfaceImpl implements StpInterface {
+
+    @Override
+    public List<String> getPermissionList(Object loginId, String loginType) {
+        // 返回此 loginId 拥有的权限列表 
+        return ...;
+    }
+
+    @Override
+    public List<String> getRoleList(Object loginId, String loginType) {
+        // 返回此 loginId 拥有的角色列表
+        return ...;
+    }
+
+}
+
+```
+关于数据的获取，建议以下方案三选一：
+1. 在网关处集成ORM框架，直接从数据库查询数据
+2. 先从Redis中获取数据，获取不到时走ORM框架查询数据库 
+3. 先从Redis中获取缓存数据，获取不到时走RPC调用子服务 (专门的权限数据提供服务) 获取
+
+
+### 3、注册全局过滤器 
+然后在网关处注册全局过滤器进行鉴权操作 
+
+``` java
+/**
+ * [Sa-Token 权限认证] 配置类 
+ * @author kong
+ */
+@Configuration
+public class SaTokenConfigure {
+	// 注册 Sa-Token全局过滤器 
+    @Bean
+    public SaReactorFilter getSaReactorFilter() {
+        return new SaReactorFilter()
+			// 拦截地址 
+			.addInclude("/**")
+			// 开放地址 
+			.addExclude("/favicon.ico")
+			// 鉴权方法：每次访问进入 
+			.setAuth(r -> {
+				// 登录验证 -- 拦截所有路由，并排除/user/doLogin 用于开放登录 
+				SaRouter.match("/**", "/user/doLogin", () -> StpUtil.checkLogin());
+				
+				// 权限认证 -- 不同模块, 校验不同权限 
+				SaRouter.match("/user/**", () -> StpUtil.checkPermission("user"));
+				SaRouter.match("/admin/**", () -> StpUtil.checkPermission("admin"));
+				SaRouter.match("/goods/**", () -> StpUtil.checkPermission("goods"));
+				SaRouter.match("/orders/**", () -> StpUtil.checkPermission("orders"));
+				
+				// ... 
+			})
+			// 异常处理方法：每次setAuth函数出现异常时进入 
+			.setError(e -> {
+				return SaResult.error(e.getMessage());
+			})
+			;
+    }
+}
+```
+
+详细操作参考：[路由拦截鉴权](/use/route-check)
+
+
+
+
+
+
--- a/sa-token-doc/doc/micro/id-token.md
+++ b/sa-token-doc/doc/micro/id-token.md
@@ -0,0 +1,228 @@
+# 微服务 - 内部服务调用鉴权 
+
+--- 
+
+
+### 一、需求场景  
+
+我们的子服务一般不能通过外网直接访问，必须通过网关转发才是一个合法的请求，这种子服务与外网的隔离一般分为两种：
+
+1. 物理隔离：子服务部署在指定的内网环境中，只有网关对外网开放 
+2. 逻辑隔离：子服务与网关同时暴露在外网，但是子服务会有一个权限拦截层保证只接受网关发送来的请求，绕过网关直接访问子服务会被提示：无效请求 
+
+这种鉴权需求牵扯到两个环节：网关转发鉴权、内部服务调用鉴权 
+
+Sa-Token提供两种解决方案：
+1. 使用 OAuth2.0 模式的凭证式，将 Client-Token 用作各个服务的身份凭证进行权限校验
+2. 使用 Id-Token 模块提供的身份校验能力，完成服务间的权限认证
+
+本篇主要讲解方案二 `Id-Token` 模块的整合步骤，其鉴权流程与 OAuth2.0 类似，不过使用方式上更加简洁（希望使用方案一的同学可参考Sa-OAuth2模块，此处不再赘述）
+
+### 二、网关转发鉴权 
+
+##### 1、引入依赖
+
+在网关处引入的依赖为（此处以 SpringCloud Gateway 为例）：
+``` xml
+<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+
+在子服务引入的依赖为：
+``` xml
+<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+
+##### 2、网关处添加Id-Token
+
+为网关添加全局过滤器：
+``` java
+/**
+ * 全局过滤器，为请求添加 Id-Token 
+ */
+@Component
+public class ForwardAuthFilter implements GlobalFilter {
+	@Override
+	public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
+		ServerHttpRequest newRequest = exchange
+				.getRequest()
+				.mutate()
+				// 为请求追加 Id-Token 参数 
+				.header(SaIdUtil.ID_TOKEN, SaIdUtil.getToken())
+				.build();
+        ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();
+        return chain.filter(newExchange);
+	}
+}
+```
+此过滤器会为 Request 请求头追加 `Id-Token` 参数，这个参数会被转发到子服务 
+
+
+##### 3、在子服务里校验参数 
+
+在子服务添加过滤器校验参数 
+``` java
+/**
+ * Sa-Token 权限认证 配置类 
+ */
+@Configuration
+public class SaTokenConfigure implements WebMvcConfigurer {
+	// 注册 Sa-Token 全局过滤器 
+    @Bean
+    public SaServletFilter getSaServletFilter() {
+        return new SaServletFilter()
+        		.addInclude("/**")
+        		.addExclude("/favicon.ico")
+        		.setAuth(r -> {
+        			// 校验 Id-Token 身份凭证 	—— 以下两句代码可简化为：SaIdUtil.checkCurrentRequestToken(); 
+        			String token = SaHolder.getRequest().getHeader(SaIdUtil.ID_TOKEN);
+        			SaIdUtil.checkToken(token);
+        		})
+        		.setError(e -> {
+        			return SaResult.error(e.getMessage());
+        		})
+        		;
+    }
+}
+```
+
+启动网关与子服务，访问测试：
+
+> 如果通过网关转发，可以正常访问，直接访问子服务会提示：`无效Id-Token：xxx`
+
+
+### 三、内部服务调用鉴权 
+
+有时候我们需要在一个服务调用另一个服务的接口，这也是需要添加`Id-Token`作为身份凭证的
+
+在服务里添加 Id-Token 流程与网关类似，我们以RPC框架 `Feign` 为例：
+
+##### 1、首先在调用方添加 FeignInterceptor
+``` java
+/**
+ * feign拦截器, 在feign请求发出之前，加入一些操作 
+ */
+@Component
+public class FeignInterceptor implements RequestInterceptor {
+	// 为 Feign 的 RCP调用 添加请求头Id-Token 
+	@Override
+	public void apply(RequestTemplate requestTemplate) {
+		requestTemplate.header(SaIdUtil.ID_TOKEN, SaIdUtil.getToken());
+	}
+}
+```
+
+##### 2、在调用接口里使用此 Interceptor 
+``` java
+/**
+ * 服务调用 
+ */
+@FeignClient(
+		name = "sp-home", 				// 服务名称 
+		configuration = FeignInterceptor.class,		// 请求拦截器 （关键代码）
+		fallbackFactory = SpCfgInterfaceFallback.class	// 服务降级处理 
+		)	
+public interface SpCfgInterface {
+
+	// 获取server端指定配置信息 
+	@RequestMapping("/SpConfig/getConfig")
+	public String getConfig(@RequestParam("key")String key);
+	
+}
+```
+
+被调用方的代码无需更改（按照网关转发鉴权处的代码注册全局过滤器），保持启动测试即可 
+
+
+### 四、Id-Token 模块详解 
+
+Id-Token —— 专门解决身份凭证问题的一个模块，它的作用不仅局限于微服务调用场景
+
+基本使用流程为：服务调用方获取Token，提交到请求中，被调用方取出Token进行校验：Token一致则校验通过，否则拒绝服务
+
+首先我们预览一下此模块的相关API：
+``` java
+// 获取当前Id-Token
+SaIdUtil.getToken();
+
+// 判断一个Id-Token是否有效
+SaIdUtil.isValid(token);
+
+// 校验一个Id-Token是否有效 (如果无效则抛出异常)
+SaIdUtil.checkToken(token);
+
+// 校验当前Request提供的Id-Token是否有效 (如果无效则抛出异常)
+SaIdUtil.checkCurrentRequestToken();
+
+// 刷新一次Id-Token (注意集群环境中不要多个服务重复调用) 
+SaIdUtil.refreshToken();
+
+// 在 Request 上储存 Id-Token 时建议使用的key
+SaIdUtil.ID_TOKEN;
+```
+
+##### 1、疑问：这个Token保存在什么地方？有没有泄露的风险？Token为永久有效还是临时有效？
+Id-Token 默认随 Sa-Token 数据一起保存在Redis中，理论上不会存在泄露的风险，每个Token默认有效期只有一天
+
+##### 2、如何主动刷新Id-Token，例如：五分钟、两小时刷新一次？
+Id-Token 刷新间隔越短，其安全性越高，每个Token的默认有效期为一天，在一天后再次获取会自动产生一个新的Token
+
+!> 需要注意的一点是：Id-Token默认的自刷新机制，并不能做到高并发可用，多个服务一起触发Token刷新可能会造成毫秒级的短暂服务失效，其只能适用于 项目开发阶段 或 低并发业务场景 
+
+因此在微服务架构下，我们需要有专门的机制主动刷新Id-Token，保证其高可用
+
+例如，我们可以专门起一个服务，使用定时任务来刷新Id-Token 
+``` java
+/**
+ * Id-Token，定时刷新
+ */
+@Configuration
+public class SaIdTokenRefreshTask {
+	// 从 0 分钟开始 每隔 5 分钟执行一次 Id-Token  
+	@Scheduled(cron = "0 0/5 * * * ? ")
+	public void refreshToken(){
+		SaIdUtil.refreshToken();
+	}
+}
+```
+
+以上的cron表达式刷新间隔可以配置为`五分钟`、`十分钟` 或 `两小时`，只要低于Id-Token的有效期（默认为一天）即可。
+
+##### 3、如果网关携带token转发的请求在落到子服务的节点上时，恰好刷新了token，导致鉴权未通过怎么办？
+Id-Token 模块在设计时，充分考虑到了这一点，在每次刷新 Token 时，旧 Token 会被作为次级 Token 存储起来，
+只要网关携带的 Token 符合新旧 Token 其一即可通过认证，直至下一次刷新，新 Token 再次作为次级 Token 将此替换掉 
+
+
+
+
+
+
--- a/sa-token-doc/doc/micro/import-intro.md
+++ b/sa-token-doc/doc/micro/import-intro.md
@@ -0,0 +1,62 @@
+
+# 微服务中使用Sa-Token 依赖引入说明 
+
+--- 
+
+虽然在 [开始] 章节已经说明了依赖引入规则，但是交流群里不少小伙伴提出bug解决到最后发现都是因为依赖引入错误导致的，此处再次重点强调一下：
+
+> **在微服务架构中使用Sa-Token时，网关和内部服务要分开引入Sa-Token依赖（不要直接在顶级父pom中引入Sa-Token）**
+
+总体来讲，我们需要关注的依赖就是两个：`sa-token-spring-boot-starter` 和 `sa-token-reactor-spring-boot-starter`，
+
+``` xml
+<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+```
+
+``` xml
+<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+```
+
+
+至于怎么分辨我们需要引入哪个呢？这个要看你使用的基础框架：
+
+对于内部基础服务来讲，我们一般都是使用SpringBoot默认的web模块：SpringMVC，
+因为这个SpringMVC是基于Servlet模型的，在这里我们需要引入的是`sa-token-spring-boot-starter`
+
+对于网关服务，大体来讲分为两种：
+- 一种是基于Servlet模型的，如：Zuul，我们需要引入的是：`sa-token-spring-boot-starter`，详细戳：[在SpringBoot环境集成](/start/example)
+- 一种是基于Reactor模型的，如：SpringCloud Gateway、ShenYu、Fizz Gateway 等等，我们需要引入的是：`sa-token-reactor-spring-boot-starter`，**并且注册全局过滤器！**，详细戳：[在WebFlux环境集成](/start/webflux-example)
+
+注：切不可直接在一个项目里同时引入这两个依赖，否则会造成项目无法启动
+
+另外，我们需要引入Redis集成包，因为我们的网关和子服务主要通过Redis来同步数据 
+``` xml
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+详细参考：[集成 Redis](/up/integ-redis)
+
+
+
+
+
+
+