ouyangxq
19745e46c1
18 个服务与公共模块重复复制的 314 字符数据库访问约束改为指向后端根唯一定义，并给索引门禁增加防退化校验。 - 18 处重复段落合并为一句指针，规则正文只在后端根 AGENTS.md 维护 - 门禁新增路由表行宽上限（根/Admin/Client/后端根/海外 PDA），防止业务规则重新回流表格 - 同步包含此前未提交的链接与锚点、表格存在性校验 - 仅索引文档与门禁脚本，未改动业务代码
34 lines
2.9 KiB
Markdown
34 lines
2.9 KiB
Markdown
# Common Security 模块指引
|
||
|
||
## 数据库访问与中文注释约束
|
||
|
||
- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。
|
||
|
||
## 职责边界
|
||
|
||
- 提供业务服务通用的 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） |
|
||
| JWT 过滤与声明映射 | `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java` |
|
||
| 当前用户与认证对象 | `AuthenticatedUser.java`、`BaiyueJwtAuthenticationToken.java`；海外 PDA 仓范围由 `JwtClaimsMapper.java` 将 `overseas_warehouse_id` 映射为 `overseasWarehouseId` |
|
||
| 会话与授权来源 | `AccessTokenSessionValidator.java`、`RedisAccessTokenSessionValidator.java`（所有服务共享会话和权限快照）、`RedisTokenKeys.java`；`HttpSessionStateVerifier.java` 每请求调用 Auth 权威状态校验，超时/错误失败关闭 |
|
||
| 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/` |
|
||
|
||
## 修改与验证
|
||
|
||
- 所有资源服务只接受 RS256/JWKS，统一 Issuer、Audience 和 `session-mode=redis`。私钥仅在 Auth，业务服务使用 JWKS 公钥缓存与共享 Redis 会话；不再支持 HMAC、claims 或 gateway 会话模式，不信任请求头携带的角色权限。
|
||
- Token Claim、Redis Key、Issuer、Audience、JWKS、会话模式或认证对象变化必须同步检查 `auth/`、`gateway/`、Nacos/部署配置和所有实际业务服务。
|
||
- `overseas_warehouse_id` 只承载 IAM 已确认的海外仓绑定；缺失、格式非法或会话已撤销时不得放宽 PDA 仓范围，Gateway 与业务服务必须 fail-closed。
|
||
- `JsonAuthenticationEntryPoint` 与 `JsonAccessDeniedHandler` 属于统一 HTTP 200 业务契约的例外：认证入口仍返回真实 401/403，供前端刷新 Token 和区分授权失败。
|
||
- Access 先校验 Redis 会话身份，再通过 `baiyue.security.session-validation-uri` 在线核对 Auth/IAM 持久化状态；禁止正结果缓存、失败降级或请求头信任。内部调用只带服务令牌和 jwtId/userId，不透传 Bearer；4 秒总超时、1 秒连接超时、不跟随重定向。
|
||
- 不降低服务端客户、会话或权限校验；密钥只从配置中心或环境变量读取。
|
||
- 从父目录运行 `mvn -pl common-security -am test`。
|