Files
eip4-platform/platform-auth/P2认证实测报告.md
zhengwr 33d793b825 feat(auth): P2-2 Spring Security 无状态 JWT 认证链路 + UserSession 引擎上下文适配
- jjwt 0.12.6 HS256;密钥配置化(EIP4_AUTH_JWT_SECRET),启动期强度校验,不入仓库
- 密码兼容:复刻 framework EncryptUtil 无盐 MD5 + 常量时间比对(侦察证据见报告)
- JwtAuthFilter:SecurityContext + 引擎 UserSession(静态 ThreadLocal)请求级 set/finally clear,16线程×200次并发隔离单测
- SecurityConfig 双链:prod 严格 401 / 非 prod 保留对拍测试通道(单测断言生产关闭)
- EntityController.buildCtx 三级优先(asUser > JWT > ADMIN),修复 JWT ctx 被 ADMIN 默认覆盖
- 实测:登录签发/过滤 16 行与 DB 吻合/伪造过期全 401;ci.sh 全绿;手册新增 §5.29-5.31

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 13:37:34 +08:00

184 lines
9.7 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# EIP4 P2-2 任务 实测报告 —— Spring Security + 无状态 JWT + UserSession 适配
> 工程:eip4-platform · 环境:本地 PG 15(`localhost:5433`),实测端口 8086/8087,连本地库自举
> 时间:2026-06-11 · 通过标准:登录签发 JWT + 带/不带/伪造/过期令牌行为正确 + JWT roles 驱动行级过滤 + 单测 ≥8
> **保真层 `com.dsasp` 一行未改**,适配全部在 `com.eip4.platform.auth.security`。
## 一、结论速览
| 项 | 结果 |
|----|------|
| 密码哈希侦察(读 framework 源码) | ✅ **无盐小写十六进制 MD5**,纯字符串相等比对 |
| JWT 选型 | ✅ **jjwt 0.12.6**(HS256 对称密钥,理由见 §三) |
| POST /api/auth/login 签发 JWT | ✅ 账号口令校验 SYS_USER → 签发含 userId/账号/姓名/depart/org/roles |
| JwtAuthFilter 填充引擎 ctx + 请求级清理 | ✅ set/clear,**并发隔离单测断言零泄漏** |
| SecurityConfig 双链按 profile | ✅ 非 prod 保留 permitAll+asUser/roles 测试通道;**prod 严格,无旁路** |
| 实测 401(无/伪造/过期令牌) | ✅ 全部 401 |
| 实测 JWT roles 驱动行级过滤 | ✅ 带 alice 令牌读 3 受控实体各 **16 行**(=alice 的行,非全量 50) |
| 单测 | ✅ **16 用例全过**(要求 ≥8) |
| CI 兼容(`scripts/ci.sh`,含 parity) | ✅ **全绿**:21/21 实体 1108 行 + C2 9/9 正例 + 3/3 负例 |
---
## 二、密码哈希侦察(证据)
侦察对象:`/Users/zhengwr/workspace/eip3/framework`(旧系统源码)。读到的口径逐条:
1. **哈希函数**:`com.dsasp.server.common.util.EncryptUtil.encodeMD5String`:
```java
MessageDigest md5 = MessageDigest.getInstance("MD5");
byte[] bytes = md5.digest(str.getBytes()); // 平台默认字符集
// 逐字节小写十六进制,b<16 补前导 0 → 32 字符
```
→ **标准小写十六进制 MD5,无盐、无迭代**。
2. **登录比对(服务端,`AuthConstroller#login`)**:按 `SYS_USER_SEARCH` 服务流,
`P.ACCOUNT = '<账号>'` + `PASSWORD = EncryptUtil.encodeMD5String(明文)`,纯相等命中。
3. **改密(`ChangePasswordView`)**:`oldPwd.equals(entity.get_Value("PASSWORD"))`、
`map.put("PASSWORD", encodeMD5String(新明文))` 落库 → 印证存储即该 MD5、比对即 `equals`。
4. **UI 登录(`LoginWindow`)**:同走 `SYS_USER_SEARCH`(按 ACCOUNT)取用户行;ctx 构建口径
(注释段)= `CURRENTUSER=pojo.get_ID()`、`CURRENTDEPART=MASTERDEPART`、`CURRENTORG=USERORGID`、
`ROLES=roleService.findRolesByUserId(userId)`——**这就是我适配引擎 ctx 的精确契约**。
**复刻**:`com.eip4.platform.auth.security.PasswordHasher.md5Hex` 逐字节复刻(保真层不动),
比对用 `MessageDigest.isEqual` 常量时间。单测断言 `MD5("123456")=e10adc3949ba59abbe56e057f20f883e`。
> 已同步《迁移手册》§5.31。
---
## 三、JWT 选型(jjwt vs spring-security-oauth2-jose)
**选 jjwt 0.12.6**,理由:
- 本系统是**自签自验**的单一签发方,不与外部 IdP 联邦、无需 JWKS/非对称密钥轮转 →
HS256 + 配置化对称密钥即足够;oauth2-jose/资源服务器栈面向 OAuth2 联邦,在此属过度设计。
- jjwt API 精简,0.12.x 强制安全默认(密钥长度校验、算法绑定),契合「最小可用」。
- 与架构选型表「Spring Security + 无状态 JWT,免 session 共享」一致。
**密钥不硬编码进仓库**:`JwtService` 构造期校验密钥存在且 ≥32 字节(HS256),缺失/过短直接启动失败。
本地默认值仅放 `application.yml`/`application-local.yml`(`${EIP4_AUTH_JWT_SECRET:dev-only-...}`,
注明生产须替换);生产经环境变量 `EIP4_AUTH_JWT_SECRET` 覆盖。
> 注:CI 用 default profile,故 default 配置须有可启动的非生产默认密钥(已加注释强标「生产须替换」)。
JWT claims:`iss/sub(账号)/userId/account/name/depart/org/roles(List)/iat/exp`;有效期默认 8h(可配)。
---
## 四、组件清单(全部 com.eip4.platform.auth.security)
| 类 | 职责 |
|----|------|
| `JwtProperties` | `eip4.auth.jwt.*` 配置(secret/expireSeconds/issuer),无内置默认密钥 |
| `JwtService` | HS256 签发/校验(过期/签名/issuer 校验);启动期密钥强度校验 |
| `PasswordHasher` | 复刻 EncryptUtil 的无盐 MD5 + 常量时间比对 |
| `SysUserService` | 只读 SELECT 校验 SYS_USER(按 ACCOUNT)+ 角色解析(复刻 RoleServiceImpl join,参数化) |
| `AuthPrincipal` | JWT claims 不可变载体(record),映射 SYS_USER 列与 LoggedInUser 契约 |
| `AuthController` | `POST /api/auth/login`,失败统一 401 含糊文案(防账号枚举) |
| `EngineContextBinder` | 把 AuthPrincipal 写入引擎 UserSession(ROLES 用 put(List));bind/clear |
| `JwtAuthFilter` | 校验 Bearer → SecurityContext + 引擎 ctx;**finally 无条件 clear** |
| `SecurityConfig` | 双链按 profile:prod 严格(未认证 401),非 prod permitAll 测试通道 |
| `AuthConfig` | `@EnableConfigurationProperties(JwtProperties)` |
**EntityController 适配(platform-metadata)**:`buildCtx` 三级优先(asUser 参 > JWT 绑定 ctx > ADMIN),
使 JWT roles 替代 asUser/roles 驱动行级过滤,且 C2 对拍旁路零回归。详见《迁移手册》§5.29。
---
## 五、实测证据(curl)
### 5.1 登录签发 JWT(8086,连 eip4ci 自举库)
```
POST /api/auth/login {"account":"alice","password":"123456"}
→ HTTP 200
{"success":true,"token":"eyJ...","expireSeconds":28800,
"userId":"USER_ALICE","account":"alice","name":"爱丽丝",
"roles":["ROLE_CUSTOMER","ROLE_PROJECT","ROLE_TASK"]}
```
### 5.2 JWT roles 驱动行级过滤(复用 C2 的 3 受控实体)
带 alice 令牌(CURRENTUSER=USER_ALICE,roles=[ROLE_CUSTOMER/PROJECT/TASK])调受控实体,
引擎按 `CREATEBY={CURRENTUSERID}` 过滤,**仅返回 alice 的行**:
| 场景 | 实体 | HTTP | 返回行数 | 期望 |
|------|------|------|---------|------|
| 带令牌(JWT roles) | EIP4PT_CUSTOMER | 200 | **16** | alice 16 行(非全量 50)✅ |
| 带令牌(JWT roles) | EIP4PT_PROJECT | 200 | **16** | ✅ |
| 带令牌(JWT roles) | EIP4PT_TASK | 200 | **16** | ✅ |
| 无令牌无 asUser | EIP4PT_CUSTOMER | 200 | 50 | ADMIN 视角不过滤(默认不变)✅ |
| C2 旁路 ?asUser=USER_BOB | EIP4PT_CUSTOMER | 200 | 17 | 测试通道仍可用 ✅ |
DB ground truth(CREATEBY 重分区后):ALICE 16 / BOB 17 / CAROL 17,逐数吻合。
> JWT roles 成功**替代** asUser/roles 参数:同一引擎过滤路径,身份来源从查询参换成 JWT claims。
### 5.3 严格鉴权(prod profile,8087)
| 场景 | HTTP | 期望 |
|------|------|------|
| 登录正确口令 | 200 | 签发令牌 ✅ |
| 登录错误口令 | 401 | 拒绝 ✅ |
| 无令牌访问 /api/entity/** | **401** | 拒绝(凭据缺失)✅ |
| 伪造签名令牌 | **401** | 拒绝 ✅ |
| 乱码令牌 | **401** | 拒绝 ✅ |
| 已过期令牌(expire=-3600s) | **401** | 拒绝 ✅ |
| 带有效令牌访问 /api/entity/** | 200 | 放行 + 过滤 16 行 ✅ |
> prod 链经 `HttpStatusEntryPoint(UNAUTHORIZED)` 使未认证返回 401(而非 Spring 默认 403,语义更正确)。
> 并排除 `UserDetailsServiceAutoConfiguration`,免生成误导性 dev 口令(JWT 认证不需内存用户)。
---
## 六、单测(16 用例,platform-auth)
`JwtServiceTest`(9):签发回读全 claim、过期被拒、异密钥伪造被拒、篡改串被拒、issuer 不符被拒、
密钥缺失/过短构造失败、乱码非 JWT 被拒、MD5 口令哈希与框架口径一致。
`EngineContextIsolationTest`(4):bind 写入再 clear 清空、过滤器请求收尾后清空、无令牌不填充、
**16 线程×200 次不同令牌并发零串号 + 收尾零残留**(并发隔离证明)。
`SecurityProfileTest`(3):**prod 链受保护路径无令牌=401**(测试旁路关闭断言)、
prod 链仍放行登录端点与 API 文档、非 prod 链 permitAll 旁路开启(对拍 CI 依赖)。
```
Tests run: 16, Failures: 0, Errors: 0, Skipped: 0 —— BUILD SUCCESS
```
---
## 七、CI 兼容
`scripts/ci.sh`(default profile,连 eip4ci):
- `--skip-parity`:编译 + 全模块单测 + ArchUnit 边界纪律 → 绿。
- 完整(含 parity):**21/21 实体 1108 行 100% 逐行一致** + C2 权限对拍 **9/9 正例 + 3/3 负例**全过。
> 关键:CI 用 default(非 prod)profile,安全层走 permitAll 测试通道,parity 的免令牌 +
> asUser/roles 旁路**零回归**——证明安全层接入未破坏对拍门禁。ArchUnit 仍绿(新代码仅依赖
> com.dsasp 的 UserSession/LoggedInUser,反向零依赖)。
---
## 八、自举数据(bootstrap-auth.sql)
位置:`platform-parity/src/main/resources/bootstrap/bootstrap-auth.sql`(幂等,在 sys+privilege 之后追加)。
内容:① SYS_USER 物理表(认证读路径列);② 测试用户 alice(SYS_USER_ID='USER_ALICE',口令 123456 的 MD5);
③ 用户组/角色链(sys_usergroupuser ⋈ sys_usergrouprole,复刻 RoleServiceImpl 读路径)→ alice 得
ROLE_CUSTOMER/PROJECT/TASK;④ 受控实体 CREATEBY 重分区(与 privilege 脚本同口径,使过滤可判别)。
---
## 九、新坑(已同步《迁移手册》)
- §5.29 JWT 上下文被 EntityController 的 ADMIN 默认覆盖(认证集成坑)。
- §5.30 引擎 UserSession 是静态 ThreadLocal,认证过滤器必须请求级 set/clear(ROLES 用 put(List))。
- §5.31 客户库 SYS_USER 口令哈希=无盐小写十六进制 MD5(侦察结论)。
## 附:产物清单
- 实现:`platform-auth/src/main/java/com/eip4/platform/auth/security/`(10 类)
- 适配:`platform-metadata/.../web/EntityController.java`(buildCtx 三级优先)
- 配置:`pom.xml`(jjwt dependencyManagement)、`platform-auth/pom.xml`(security/jwt/jdbc)、
`platform-app/.../application.yml` + `application-local.yml`(JWT 配置 + 排除 UserDetailsService 自动配)
- 自举:`platform-parity/.../bootstrap/bootstrap-auth.sql`
- 单测:`platform-auth/src/test/.../security/`(3 类 16 用例)
- 报告:本文件;新坑进《迁移手册》§5.29/5.30/5.31