296 lines
9.3 KiB
Markdown
296 lines
9.3 KiB
Markdown
---
|
||
name: 0008-datai-salesforce-auth-immediate-fixes
|
||
description: datai-salesforce-auth 模块立即修复事项架构决策
|
||
---
|
||
|
||
# 架构决策记录: datai-salesforce-auth 模块立即修复事项
|
||
|
||
## 背景
|
||
|
||
经过对 `datai-salesforce-auth` 模块的详细扫描和分析，发现了以下影响系统编译、安全性和稳定性的问题：
|
||
|
||
1. **语法错误**: DataiSfLoginHistoryController 和 DataiSfLoginSessionController 中存在多余的右括号，导致代码无法编译
|
||
2. **密码加密不安全**: 使用对称加密存储密码，可以解密还原明文，存在数据泄露风险
|
||
3. **敏感信息日志泄露**: 日志中记录了 Session ID、用户名等敏感信息，存在日志泄露风险
|
||
4. **缺少请求频率限制**: 登录接口没有请求频率限制，可能遭受暴力破解攻击
|
||
|
||
这些问题需要立即修复，以确保系统的正常运行和数据安全。
|
||
|
||
## 决策
|
||
|
||
针对上述问题，我们做出以下架构决策：
|
||
|
||
### 决策 1: 语法错误修复
|
||
**方案**: 直接修复语法错误，移除多余的右括号
|
||
**理由**: 语法错误导致代码无法编译，必须立即修复
|
||
**实施**:
|
||
- 在 DataiSfLoginHistoryController.java:82 移除多余的右括号
|
||
- 在 DataiSfLoginSessionController.java:82 移除多余的右括号
|
||
|
||
### 决策 2: 密码加密方式调整
|
||
**方案**: 使用不可逆的哈希算法（BCrypt）替代对称加密
|
||
**理由**:
|
||
- 对称加密可以解密还原明文，存在数据泄露风险
|
||
- BCrypt 是业界标准的密码哈希算法，具有抗彩虹表攻击能力
|
||
- BCrypt 自动处理盐值，提高安全性
|
||
|
||
**实施**:
|
||
- 修改数据库表结构，将 `password_encrypted` 字段改为 `password_hash`
|
||
- 修改 SalesforceLoginServiceImpl.java 中的密码存储逻辑
|
||
- 使用 BCrypt.hashpw() 方法对密码进行哈希
|
||
- 使用 BCrypt.checkpw() 方法验证密码
|
||
|
||
### 决策 3: 敏感信息日志脱敏
|
||
**方案**: 对敏感信息进行脱敏处理后再记录日志
|
||
**理由**:
|
||
- 防止日志泄露导致敏感信息泄露
|
||
- 满足安全合规要求（如 GDPR、等保三级）
|
||
- 保留足够的调试信息（如 Session ID 前 8 位）
|
||
|
||
**实施**:
|
||
- 创建脱敏工具类 `SensitiveInfoMasker`
|
||
- 实现 `maskSensitiveInfo(String info)` 方法
|
||
- 在 SalesforceLoginServiceImpl.java 中所有日志记录处使用脱敏方法
|
||
- 脱敏规则：Session ID 只显示前 8 位，用户 ID 只显示前 4 位
|
||
|
||
### 决策 4: 请求频率限制
|
||
**方案**: 使用 Spring Security 或 Redis 实现请求频率限制
|
||
**理由**:
|
||
- 防止暴力破解攻击
|
||
- 保护系统资源不被滥用
|
||
- 符合安全最佳实践
|
||
|
||
**实施**:
|
||
- 使用 Spring Security 的 `@RateLimiter` 注解
|
||
- 配置每分钟最多 5 次登录尝试
|
||
- 超过限制时返回明确的错误信息（HTTP 429）
|
||
- 使用 Redis 存储请求计数
|
||
|
||
## 备选方案
|
||
|
||
### 决策 1: 语法错误修复
|
||
**无备选方案**: 语法错误必须直接修复，无其他方案
|
||
|
||
### 决策 2: 密码加密方式调整
|
||
|
||
#### 方案 A: BCrypt（已选择）
|
||
**优点**:
|
||
- 业界标准，广泛使用
|
||
- 自动处理盐值
|
||
- 抗彩虹表攻击
|
||
- 内置成本因子，可调整计算复杂度
|
||
|
||
**缺点**:
|
||
- 计算较慢（但这是优点，防止暴力破解）
|
||
- 需要修改数据库表结构
|
||
|
||
#### 方案 B: PBKDF2
|
||
**优点**:
|
||
- NIST 推荐算法
|
||
- 可配置迭代次数
|
||
- 安全性高
|
||
|
||
**缺点**:
|
||
- 不如 BCrypt 常用
|
||
- 需要手动处理盐值
|
||
|
||
#### 方案 C: Argon2
|
||
**优点**:
|
||
- 密码哈希竞赛冠军
|
||
- 抗 GPU/ASIC 攻击
|
||
- 可配置内存和计算成本
|
||
|
||
**缺点**:
|
||
- 相对较新，兼容性可能有问题
|
||
- 需要额外的依赖
|
||
|
||
**选择理由**: BCrypt 是业界标准，成熟稳定，安全性足够，易于实施。
|
||
|
||
### 决策 3: 敏感信息日志脱敏
|
||
|
||
#### 方案 A: 自定义脱敏工具类（已选择）
|
||
**优点**:
|
||
- 灵活，可定制脱敏规则
|
||
- 不依赖外部库
|
||
- 易于维护
|
||
|
||
**缺点**:
|
||
- 需要自己实现
|
||
|
||
#### 方案 B: 使用 Logback Masking 插件
|
||
**优点**:
|
||
- 配置简单
|
||
- 自动脱敏
|
||
|
||
**缺点**:
|
||
- 灵活性差
|
||
- 需要额外配置
|
||
|
||
#### 方案 C: 使用第三方库（如 logback-mask）
|
||
**优点**:
|
||
- 开箱即用
|
||
- 功能丰富
|
||
|
||
**缺点**:
|
||
- 增加依赖
|
||
- 可能不满足定制需求
|
||
|
||
**选择理由**: 自定义脱敏工具类更灵活，易于维护，不增加外部依赖。
|
||
|
||
### 决策 4: 请求频率限制
|
||
|
||
#### 方案 A: Spring Security @RateLimiter（已选择）
|
||
**优点**:
|
||
- 与 Spring Security 集成良好
|
||
- 使用注解，易于使用
|
||
- 支持 Redis 分布式部署
|
||
|
||
**缺点**:
|
||
- 需要 Redis 依赖
|
||
|
||
#### 方案 B: 自定义拦截器
|
||
**优点**:
|
||
- 不依赖外部库
|
||
- 灵活可定制
|
||
|
||
**缺点**:
|
||
- 需要自己实现
|
||
- 不支持分布式部署
|
||
|
||
#### 方案 C: 使用 Guava RateLimiter
|
||
**优点**:
|
||
- 轻量级
|
||
- 性能好
|
||
|
||
**缺点**:
|
||
- 单机限流，不支持分布式
|
||
- 需要手动集成
|
||
|
||
**选择理由**: Spring Security @RateLimiter 与现有架构集成良好，支持分布式部署。
|
||
|
||
## 影响
|
||
|
||
### 系统架构影响
|
||
1. **密码加密方式变更**: 需要修改数据库表结构，影响现有登录历史数据
|
||
2. **日志脱敏**: 需要修改所有日志记录处，影响调试体验
|
||
3. **请求频率限制**: 需要添加 Redis 依赖，影响部署架构
|
||
|
||
### 开发流程影响
|
||
1. **语法错误修复**: 立即修复，不影响开发流程
|
||
2. **密码加密方式变更**: 需要数据迁移脚本，影响开发流程
|
||
3. **日志脱敏**: 需要修改所有日志记录处，影响开发流程
|
||
4. **请求频率限制**: 需要添加 Redis 配置，影响开发流程
|
||
|
||
### 运维管理影响
|
||
1. **密码加密方式变更**: 需要执行数据迁移脚本，影响运维
|
||
2. **日志脱敏**: 不影响运维，反而提高安全性
|
||
3. **请求频率限制**: 需要部署 Redis，影响运维
|
||
|
||
### 用户体验影响
|
||
1. **密码加密方式变更**: 不影响用户体验
|
||
2. **日志脱敏**: 不影响用户体验
|
||
3. **请求频率限制**: 可能影响用户体验（频繁登录时会被限制）
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
1. **密码加密方式变更风险**:
|
||
- **风险**: 现有登录历史数据无法使用
|
||
- **概率**: 高
|
||
- **缓解措施**: 提供数据迁移脚本，保留旧数据作为备份
|
||
|
||
2. **日志脱敏风险**:
|
||
- **风险**: 调试困难，无法看到完整信息
|
||
- **概率**: 中
|
||
- **缓解措施**: 提供调试模式开关，调试时可关闭脱敏
|
||
|
||
3. **请求频率限制风险**:
|
||
- **风险**: 误伤正常用户
|
||
- **概率**: 低
|
||
- **缓解措施**: 提供清晰的错误信息，用户知道被限制的原因
|
||
|
||
### 业务风险
|
||
1. **密码加密方式变更风险**:
|
||
- **风险**: 用户需要重新登录
|
||
- **概率**: 高
|
||
- **缓解措施**: 提前通知用户，说明变更原因
|
||
|
||
2. **请求频率限制风险**:
|
||
- **风险**: 自动登录可能被限制
|
||
- **概率**: 低
|
||
- **缓解措施**: 自动登录不受频率限制限制
|
||
|
||
### 实施风险
|
||
1. **数据库表结构变更风险**:
|
||
- **风险**: 表结构变更失败
|
||
- **概率**: 低
|
||
- **缓解措施**: 在测试环境充分测试，准备回滚脚本
|
||
|
||
## 回滚策略
|
||
|
||
### 决策 1: 语法错误修复
|
||
**回滚策略**: 使用 Git 回滚到修复前的版本
|
||
|
||
### 决策 2: 密码加密方式变更
|
||
**回滚策略**:
|
||
1. 恢复数据库表结构（添加 `password_encrypted` 字段）
|
||
2. 恢复代码（使用对称加密）
|
||
3. 从备份恢复数据
|
||
|
||
### 决策 3: 敏感信息日志脱敏
|
||
**回滚策略**: 移除脱敏逻辑，恢复原始日志记录
|
||
|
||
### 决策 4: 请求频率限制
|
||
**回滚策略**: 移除 `@RateLimiter` 注解，移除 Redis 配置
|
||
|
||
## 验收标准
|
||
|
||
### 决策 1: 语法错误修复
|
||
- [ ] AC1: 项目能够正常编译，无编译错误
|
||
- [ ] AC2: 登录功能正常工作
|
||
- [ ] AC3: 自动登录功能正常工作
|
||
|
||
### 决策 2: 密码加密方式变更
|
||
- [ ] AC1: 数据库表结构已更新（`password_hash` 字段已添加）
|
||
- [ ] AC2: 密码使用 BCrypt 哈希存储
|
||
- [ ] AC3: 密码验证使用 BCrypt.checkpw() 方法
|
||
- [ ] AC4: 现有登录历史数据已迁移
|
||
- [ ] AC5: 登录功能正常工作
|
||
|
||
### 决策 3: 敏感信息日志脱敏
|
||
- [ ] AC1: 日志中 Session ID 只显示前 8 位
|
||
- [ ] AC2: 日志中用户 ID 只显示前 4 位
|
||
- [ ] AC3: 所有日志记录处都使用了脱敏方法
|
||
- [ ] AC4: 调试模式开关正常工作
|
||
|
||
### 决策 4: 请求频率限制
|
||
- [ ] AC1: 每分钟最多 5 次登录尝试
|
||
- [ ] AC2: 超过限制时返回 HTTP 429 错误
|
||
- [ ] AC3: 错误信息清晰明确
|
||
- [ ] AC4: 自动登录不受频率限制限制
|
||
- [ ] AC5: Redis 存储请求计数正常工作
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 认证模块架构图
|
||
- **具体节点**: [DataiSalesforceAuth](../../Authentication.canvas) - datai-salesforce-auth 模块
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源。
|
||
|
||
- [需求文档](../requirements/REQ-008.md) - datai-salesforce-auth 模块立即修复事项
|
||
- [BCrypt 官方文档](https://bcrypt-generator.com/) - BCrypt 算法说明
|
||
- [Spring Security 文档](https://docs.spring.io/spring-security/reference/) - Spring Security Rate Limiting
|
||
- [OWASP 密码存储备忘单](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) - 密码存储最佳实践
|
||
- [等保三级要求](https://www.tc260.org.cn/) - 中国网络安全等级保护三级要求
|