28 lines
2.4 KiB
Markdown
28 lines
2.4 KiB
Markdown
# Common Security 模块指引
|
|
|
|
## 职责边界
|
|
|
|
- 提供业务服务通用的 JWT 解码、认证过滤、Redis Access Token 会话校验、认证用户上下文及 401/403 JSON 响应。
|
|
- 角色、权限、租户成员关系由 `iam/` 维护；本模块不实现 RBAC 管理业务。网关的 Reactive 安全链位于 `gateway/`。
|
|
|
|
## 快速索引
|
|
|
|
| 功能 | 入口 |
|
|
|---|---|
|
|
| 安全链自动配置 | `src/main/java/com/baiyue/common/security/BaiyueSecurityAutoConfiguration.java` |
|
|
| JWT 解码模式 | `JwksJwtDecoderAutoConfiguration.java`（国内与海外统一 RS256/JWKS）；`HmacJwtDecoderAutoConfiguration.java` 仅作当前开发阶段清理前的旧实现定位，不得作为跨区域共享密钥方案 |
|
|
| JWT 过滤与声明映射 | `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java` |
|
|
| 当前用户与认证对象 | `AuthenticatedUser.java`、`BaiyueJwtAuthenticationToken.java` |
|
|
| 会话与授权来源 | `AccessTokenSessionValidator.java`、`RedisAccessTokenSessionValidator.java`（国内登录 Token 即时失效）、`ClaimsAccessTokenSessionValidator.java`（海外访问 Token 本地短时 Claims）、`RedisTokenKeys.java` |
|
|
| 401/403 响应 | `JsonAuthenticationEntryPoint.java`、`JsonAccessDeniedHandler.java` |
|
|
| 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
|
|
| 安全回归测试 | `src/test/java/com/baiyue/common/security/` |
|
|
|
|
## 修改与验证
|
|
|
|
- 所有资源服务统一使用 `jwt-mode=jwks`、RS256、Issuer 和 JWKS；国内服务验证国内 Audience 并使用 `session-mode=redis`，海外服务只接受登录/刷新时签发的海外 Audience Token 并使用 `session-mode=claims`，不得访问国内 Redis。海外服务应缓存 JWKS 并在密钥轮换时刷新，不得每个请求访问国内 Auth；不得重新引入跨区域共享 HS256 密钥，也不得让海外服务接受国内 Token。
|
|
- Token Claim、Redis Key、Issuer、Audience、JWKS、会话模式或认证对象变化必须同步检查 `auth/`、`gateway/`、Nacos/部署配置和所有实际业务服务。
|
|
- `JsonAuthenticationEntryPoint` 与 `JsonAccessDeniedHandler` 属于统一 HTTP 200 业务契约的例外：认证入口仍返回真实 401/403，供前端刷新 Token 和区分授权失败。
|
|
- 不降低服务端租户、会话或权限校验；密钥只从配置中心或环境变量读取。
|
|
- 从父目录运行 `mvn -pl common-security -am test`。
|