Id-Token 模块更名为 Same-Token

2026-02-27 16:50:24 +08:00 · 2022-10-24 12:25:22 +08:00
parent 00886066e3
commit 2dc0a44dfe
34 changed files with 564 additions and 180 deletions
--- a/sa-token-doc/_sidebar.md
+++ b/sa-token-doc/_sidebar.md
@@ -56,7 +56,7 @@
 - **微服务**
 	- [分布式Session会话](/micro/dcs-session)
 	- [网关统一鉴权](/micro/gateway-auth)
-	- [内部服务外网隔离](/micro/id-token)
+	- [内部服务外网隔离](/micro/same-token)
 	- [依赖引入说明](/micro/import-intro)

 - **插件**
--- a/sa-token-doc/micro/same-token.md
+++ b/sa-token-doc/micro/same-token.md
@@ -14,9 +14,9 @@

 Sa-Token提供两种解决方案：
 1. 使用 OAuth2.0 模式的凭证式，将 Client-Token 用作各个服务的身份凭证进行权限校验
-2. 使用 Id-Token 模块提供的身份校验能力，完成服务间的权限认证
+2. 使用 Same-Token 模块提供的身份校验能力，完成服务间的权限认证

-本篇主要讲解方案二 `Id-Token` 模块的整合步骤，其鉴权流程与 OAuth2.0 类似，不过使用方式上更加简洁（希望使用方案一的同学可参考Sa-OAuth2模块，此处不再赘述）
+本篇主要讲解方案二 `Same-Token` 模块的整合步骤，其鉴权流程与 OAuth2.0 类似，不过使用方式上更加简洁（希望使用方案一的同学可参考Sa-OAuth2模块，此处不再赘述）

 ### 二、网关转发鉴权 

@@ -88,12 +88,12 @@ implementation 'org.apache.commons:commons-pool2'
 ```
 <!---------------------------- tabs:end ------------------------------>

-##### 2、网关处添加Id-Token
+##### 2、网关处添加Same-Token

 为网关添加全局过滤器：
 ``` java
 /**
- * 全局过滤器，为请求添加 Id-Token 
+ * 全局过滤器，为请求添加 Same-Token 
 */
@Component
 public class ForwardAuthFilter implements GlobalFilter {
@@ -102,15 +102,15 @@ public class ForwardAuthFilter implements GlobalFilter {
 		ServerHttpRequest newRequest = exchange
 				.getRequest()
 				.mutate()
-				// 为请求追加 Id-Token 参数 
-				.header(SaIdUtil.ID_TOKEN, SaIdUtil.getToken())
+				// 为请求追加 Same-Token 参数 
+				.header(SaSameUtil.SAME_TOKEN, SaSameUtil.getToken())
 				.build();
        ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();
        return chain.filter(newExchange);
 	}
 }
 ```
-此过滤器会为 Request 请求头追加 `Id-Token` 参数，这个参数会被转发到子服务 
+此过滤器会为 Request 请求头追加 `Same-Token` 参数，这个参数会被转发到子服务 


 ##### 3、在子服务里校验参数 
@@ -129,9 +129,9 @@ public class SaTokenConfigure implements WebMvcConfigurer {
        		.addInclude("/**")
        		.addExclude("/favicon.ico")
        		.setAuth(obj -> {
-        			// 校验 Id-Token 身份凭证 	—— 以下两句代码可简化为：SaIdUtil.checkCurrentRequestToken(); 
-        			String token = SaHolder.getRequest().getHeader(SaIdUtil.ID_TOKEN);
-        			SaIdUtil.checkToken(token);
+        			// 校验 Same-Token 身份凭证 	—— 以下两句代码可简化为：SaSameUtil.checkCurrentRequestToken(); 
+        			String token = SaHolder.getRequest().getHeader(SaSameUtil.SAME_TOKEN);
+        			SaSameUtil.checkToken(token);
        		})
        		.setError(e -> {
        			return SaResult.error(e.getMessage());
@@ -143,14 +143,14 @@ public class SaTokenConfigure implements WebMvcConfigurer {

 启动网关与子服务，访问测试：

-> 如果通过网关转发，可以正常访问，直接访问子服务会提示：`无效Id-Token：xxx`
+> 如果通过网关转发，可以正常访问，直接访问子服务会提示：`无效Same-Token：xxx`


 ### 三、服务内部调用鉴权 

-有时候我们需要在一个服务调用另一个服务的接口，这也是需要添加`Id-Token`作为身份凭证的
+有时候我们需要在一个服务调用另一个服务的接口，这也是需要添加`Same-Token`作为身份凭证的

-在服务里添加 Id-Token 流程与网关类似，我们以RPC框架 `Feign` 为例：
+在服务里添加 Same-Token 流程与网关类似，我们以RPC框架 `Feign` 为例：

 ##### 1、首先在调用方添加 FeignInterceptor
 ``` java
@@ -159,10 +159,10 @@ public class SaTokenConfigure implements WebMvcConfigurer {
 */
@Component
 public class FeignInterceptor implements RequestInterceptor {
-	// 为 Feign 的 RCP调用 添加请求头Id-Token 
+	// 为 Feign 的 RCP调用 添加请求头Same-Token 
 	@Override
 	public void apply(RequestTemplate requestTemplate) {
-		requestTemplate.header(SaIdUtil.ID_TOKEN, SaIdUtil.getToken());
+		requestTemplate.header(SaSameUtil.SAME_TOKEN, SaSameUtil.getToken());
 	}
 }
 ```
@@ -189,63 +189,63 @@ public interface SpCfgInterface {
 被调用方的代码无需更改（按照网关转发鉴权处的代码注册全局过滤器），保持启动测试即可 


-### 四、Id-Token 模块详解 
+### 四、Same-Token 模块详解 

-Id-Token —— 专门解决身份凭证问题的一个模块，它的作用不仅局限于微服务调用场景
+Same-Token —— 专门解决同源系统互相调用时的身份认证校验，它的作用不仅局限于微服务调用场景

 基本使用流程为：服务调用方获取Token，提交到请求中，被调用方取出Token进行校验：Token一致则校验通过，否则拒绝服务

 首先我们预览一下此模块的相关API：
 ``` java
-// 获取当前Id-Token
-SaIdUtil.getToken();
+// 获取当前Same-Token
+SaSameUtil.getToken();

-// 判断一个Id-Token是否有效
-SaIdUtil.isValid(token);
+// 判断一个Same-Token是否有效
+SaSameUtil.isValid(token);

-// 校验一个Id-Token是否有效 (如果无效则抛出异常)
-SaIdUtil.checkToken(token);
+// 校验一个Same-Token是否有效 (如果无效则抛出异常)
+SaSameUtil.checkToken(token);

-// 校验当前Request提供的Id-Token是否有效 (如果无效则抛出异常)
-SaIdUtil.checkCurrentRequestToken();
+// 校验当前Request提供的Same-Token是否有效 (如果无效则抛出异常)
+SaSameUtil.checkCurrentRequestToken();

-// 刷新一次Id-Token (注意集群环境中不要多个服务重复调用) 
-SaIdUtil.refreshToken();
+// 刷新一次Same-Token (注意集群环境中不要多个服务重复调用) 
+SaSameUtil.refreshToken();

-// 在 Request 上储存 Id-Token 时建议使用的key
-SaIdUtil.ID_TOKEN;
+// 在 Request 上储存 Same-Token 时建议使用的key
+SaSameUtil.SAME_TOKEN;
 ```

 ##### 1、疑问：这个Token保存在什么地方？有没有泄露的风险？Token为永久有效还是临时有效？
-Id-Token 默认随 Sa-Token 数据一起保存在Redis中，理论上不会存在泄露的风险，每个Token默认有效期只有一天
+Same-Token 默认随 Sa-Token 数据一起保存在Redis中，理论上不会存在泄露的风险，每个Token默认有效期只有一天

-##### 2、如何主动刷新Id-Token，例如：五分钟、两小时刷新一次？
-Id-Token 刷新间隔越短，其安全性越高，每个Token的默认有效期为一天，在一天后再次获取会自动产生一个新的Token
+##### 2、如何主动刷新Same-Token，例如：五分钟、两小时刷新一次？
+Same-Token 刷新间隔越短，其安全性越高，每个Token的默认有效期为一天，在一天后再次获取会自动产生一个新的Token

-!> 需要注意的一点是：Id-Token默认的自刷新机制，并不能做到高并发可用，多个服务一起触发Token刷新可能会造成毫秒级的短暂服务失效，其只能适用于 项目开发阶段 或 低并发业务场景 
+!> 需要注意的一点是：Same-Token默认的自刷新机制，并不能做到高并发可用，多个服务一起触发Token刷新可能会造成毫秒级的短暂服务失效，其只能适用于 项目开发阶段 或 低并发业务场景 

-因此在微服务架构下，我们需要有专门的机制主动刷新Id-Token，保证其高可用
+因此在微服务架构下，我们需要有专门的机制主动刷新Same-Token，保证其高可用

-例如，我们可以专门起一个服务，使用定时任务来刷新Id-Token 
+例如，我们可以专门起一个服务，使用定时任务来刷新Same-Token 
 ``` java
 /**
- * Id-Token，定时刷新
+ * Same-Token，定时刷新
 */
@Configuration
-public class SaIdTokenRefreshTask {
-	// 从 0 分钟开始 每隔 5 分钟执行一次 Id-Token  
+public class SaSameTokenRefreshTask {
+	// 从 0 分钟开始 每隔 5 分钟执行一次 Same-Token  
 	@Scheduled(cron = "0 0/5 * * * ? ")
 	public void refreshToken(){
-		SaIdUtil.refreshToken();
+		SaSameUtil.refreshToken();
 	}
 }
 ```

-以上的cron表达式刷新间隔可以配置为`五分钟`、`十分钟` 或 `两小时`，只要低于Id-Token的有效期（默认为一天）即可。
+以上的cron表达式刷新间隔可以配置为`五分钟`、`十分钟` 或 `两小时`，只要低于Same-Token的有效期（默认为一天）即可。

 ##### 3、如果网关携带token转发的请求在落到子服务的节点上时，恰好刷新了token，导致鉴权未通过怎么办？
-Id-Token 模块在设计时，充分考虑到了这一点，在每次刷新 Token 时，旧 Token 会被作为次级 Token 存储起来，
-只要网关携带的 Token 符合新旧 Token 其一即可通过认证，直至下一次刷新，新 Token 再次作为次级 Token 将此替换掉 
+Same-Token 模块在每次刷新 Token 时，旧 Token 会被作为次级 Token 存储起来，
+只要网关携带的 Token 符合新旧 Token 其一即可通过认证，直至下一次刷新，新 Token 再次作为次级 Token 将此替换掉。



--- a/sa-token-doc/more/noun-intro.md
+++ b/sa-token-doc/more/noun-intro.md
@@ -13,7 +13,7 @@ Sa-Token 无意发明任何晦涩概念提升逼格，但在处理 issue 、Q群
 - temp-token：指通过 `SaTempUtil.createToken()` 临时验证模块产生的Token，也称：临时Token。
 - Access-Token：在 OAuth2 模块产生的身份令牌，也称：访问令牌、资源令牌。
 - Refresh-Token：在 OAuth2 模块产生的刷新令牌，也称：刷新令牌。
- Id-Token：在 SaIdUtil 模块生成的Token令牌，用于提供子服务外网隔离功能。
+- Same-Token：在 SaSameUtil 模块生成的Token令牌，用于提供子服务外网隔离功能。


 #### 两种过期时间：
--- a/sa-token-doc/plugin/dubbo-extend.md
+++ b/sa-token-doc/plugin/dubbo-extend.md
@@ -60,9 +60,9 @@ implementation 'cn.dev33:sa-token-context-dubbo:${sa.top.version}'

 ### RPC调用鉴权

-在之前的 [Id-Token](/micro/id-token) 章节，我们演示了基于 Feign 的 RPC 调用鉴权，下面我们演示一下在 Dubbo 中如何集成 Id-Token 模块。
+在之前的 [Same-Token](/micro/same-token) 章节，我们演示了基于 Feign 的 RPC 调用鉴权，下面我们演示一下在 Dubbo 中如何集成 Same-Token 模块。

-其实思路和 Feign 模式一致，在 [ 调用端 ] 追加 Id-Token 参数，在 [ 被调用端 ] 校验这个 Id-Token 参数：
+其实思路和 Feign 模式一致，在 [ 调用端 ] 追加 Same-Token 参数，在 [ 被调用端 ] 校验这个 Same-Token 参数：

 - 校验通过：调用成功。
 - 校验不通过：通过失败，抛出异常。
@@ -78,18 +78,18 @@ implementation 'cn.dev33:sa-token-context-dubbo:${sa.top.version}'
 ``` yaml
 sa-token: 
 	# 打开 RPC 调用鉴权 
-	check-id-token: true
+	check-same-token: true
 ```
 <!------------- tab:properties 风格  ------------->
 ``` properties
 # 打开 RPC 调用鉴权 
-sa-token.check-id-token=true
+sa-token.check-same-token=true
 ```
 <!---------------------------- tabs:end ---------------------------->


 ##### 方式二、自建 Dubbo 过滤器校验
-此方式略显繁琐，好处是除了Id-Token，我们还可以添加其它自定义参数 (attachment)。
+此方式略显繁琐，好处是除了Same-Token，我们还可以添加其它自定义参数 (attachment)。

 1、在 [ 调用端 ] 的 `\resources\META-INF\dubbo\` 目录新建 `org.apache.dubbo.rpc.Filter` 文件
 ``` html
@@ -105,7 +105,7 @@ import org.apache.dubbo.common.constants.CommonConstants;
 import org.apache.dubbo.common.extension.Activate;
 import org.apache.dubbo.rpc.*;

-import cn.dev33.satoken.id.SaIdUtil;
+import cn.dev33.satoken.same.SaSameUtil;

 /**
 * Sa-Token 整合 Dubbo Consumer端过滤器 
@@ -116,8 +116,8 @@ public class DubboConsumerFilter implements Filter {
 	@Override
 	public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
 		
-		// 追加 Id-Token 参数 
-		RpcContext.getContext().setAttachment(SaIdUtil.ID_TOKEN, SaIdUtil.getToken());
+		// 追加 Same-Token 参数 
+		RpcContext.getContext().setAttachment(SaSameUtil.SAME_TOKEN, SaSameUtil.getToken());
 		
 		// 如果有其他自定义附加数据，如租户
 		// RpcContext.getContext().setAttachment("tenantContext", tenantContext);
@@ -144,7 +144,7 @@ import org.apache.dubbo.common.constants.CommonConstants;
 import org.apache.dubbo.common.extension.Activate;
 import org.apache.dubbo.rpc.*;

-import cn.dev33.satoken.id.SaIdUtil;
+import cn.dev33.satoken.same.SaSameUtil;

 /**
 * Sa-Token 整合 Dubbo Provider端过滤器 
@@ -155,9 +155,9 @@ public class DubboProviderFilter implements Filter {
 	@Override
 	public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
 		
-		// 取出 Id-Token 进行校验 
-		String idToken = invocation.getAttachment(SaIdUtil.ID_TOKEN);
-		SaIdUtil.checkToken(idToken);
+		// 取出 Same-Token 进行校验 
+		String sameToken = invocation.getAttachment(SaSameUtil.SAME_TOKEN);
+		SaSameUtil.checkToken(sameToken);
 		
 		// 取出其他自定义附加数据
 		// TenantContext tenantContext = invocation.getAttachment("tenantContext");
@@ -170,5 +170,5 @@ public class DubboProviderFilter implements Filter {
 ```


-然后我们就可以进行安全的 RPC 调用了，不带有 Id-Token 参数的调用都会抛出异常，无法调用成功。
+然后我们就可以进行安全的 RPC 调用了，不带有 Same-Token 参数的调用都会抛出异常，无法调用成功。

--- a/sa-token-doc/plugin/grpc-extend.md
+++ b/sa-token-doc/plugin/grpc-extend.md
@@ -8,7 +8,7 @@

 1. 在 [ 被调用端 ] 安全的调用 Sa-Token 相关 API。
 2. 在 [ 调用端 ] 登录的会话，其登录状态可以自动传递到 [ 被调用端 ] ；在 [ 被调用端 ] 登录的会话，其登录状态可以自动回传到 [ 调用端 ]
-3. id-token 安全校验
+3. Same-Token 安全校验

 ---
 和dubbo插件一样，具有以下限制：
@@ -38,7 +38,7 @@ implementation 'cn.dev33:sa-token-context-grpc:${sa.top.version}'


 ---
-### 开启id-token校验：
+### 开启 Same-Token 校验：
 直接在 `application.yml` 配置即可：

 <!---------------------------- tabs:start ---------------------------->
@@ -46,11 +46,11 @@ implementation 'cn.dev33:sa-token-context-grpc:${sa.top.version}'
 ``` yaml
 sa-token: 
 	# 打开 RPC 调用鉴权 
-	check-id-token: true
+	check-same-token: true
 ```
 <!------------- tab:properties 风格  ------------->
 ``` properties
 # 打开 RPC 调用鉴权 
-sa-token.check-id-token=true
+sa-token.check-same-token=true
 ```
 <!---------------------------- tabs:end ---------------------------->
--- a/sa-token-doc/use/config.md
+++ b/sa-token-doc/use/config.md
@@ -134,10 +134,10 @@ public class SaTokenConfigure {
 | isPrint				| Boolean	| true		| 是否在初始化配置时打印版本字符画													|
 | isLog					| Boolean	| false		| 是否打印操作日志																	|
 | jwtSecretKey			| String	| null		| jwt秘钥 （只有集成 `sa-token-temp-jwt` 模块时此参数才会生效），[参考：和 jwt 集成](/plugin/jwt-extend)	|
-| idTokenTimeout		| long		| 86400		| Id-Token的有效期 （单位: 秒），[参考：内部服务外网隔离](/micro/id-token)					|
+| sameTokenTimeout		| long		| 86400		| Same-Token的有效期 （单位: 秒），[参考：内部服务外网隔离](/micro/same-token)					|
 | basic					| String	| ""		| Http Basic 认证的账号和密码 [参考：Http Basic 认证](/up/basic-auth)						|
 | currDomain			| String	| null		| 配置当前项目的网络访问地址													|
-| checkIdToken			| Boolean		| false		| 是否校验Id-Token（部分rpc插件有效）															|
+| checkSameToken			| Boolean		| false		| 是否校验Same-Token（部分rpc插件有效）															|
 | cookie				| Object	| new SaCookieConfig()	| Cookie配置对象															|

 Cookie相关配置：