ShaoHua
182 lines
7.3 KiB
Markdown
182 lines
7.3 KiB
Markdown
# 06.1 - 云同步（安全进阶）：服务端账户/凭据与策略实现方案
|
|
|
|
## 1. 目标
|
|
|
|
为 `04-*`（基础能力）与 `06-*`（落盘策略）提供服务端底层安全实现的具体方案，确保账户密码存储、Token 管理、二次认证及安全策略下发具备生产级安全性。
|
|
|
|
## 2. 账户与密码安全存储
|
|
|
|
服务端不应存储明文密码，需采用强哈希算法进行加盐处理。
|
|
|
|
### 存储结构 (Users 表)
|
|
|
|
- `UserId`: `Guid` (主键)
|
|
- `UserName`: `string` (唯一索引)
|
|
- `PasswordHash`: `string` (存储哈希后的结果)
|
|
- `PasswordSalt`: `string` (若哈希算法自带 Salt，如 BCrypt/Argon2，则可省略)
|
|
- `Role`: `string` (用户角色，如 admin/user)
|
|
- `CreatedAtUtc`: `DateTime`
|
|
- `UpdatedAtUtc`: `DateTime`
|
|
|
|
### 哈希算法建议
|
|
|
|
- **算法**: `Argon2id` (推荐) 或 `BCrypt`。
|
|
- **配置**: 迭代次数、内存占用、并行度应符合 OWASP 最新建议。
|
|
|
|
***
|
|
|
|
## 3. Token 管理 (JWT)
|
|
|
|
采用 JSON Web Token (JWT) 作为会话凭据，并支持细粒度权限控制。
|
|
|
|
### Token 结构 (Payload)
|
|
|
|
```json
|
|
{
|
|
"sub": "UserId",
|
|
"name": "UserName",
|
|
"role": "Role",
|
|
"perms": ["tasks:read", "sync:write", "policy:read"],
|
|
"iat": 1712000000,
|
|
"exp": 1712003600,
|
|
"iss": "Hua.Todo.Server",
|
|
"aud": "Hua.Todo.Client",
|
|
"isStepUp": false // 是否通过了二次认证
|
|
}
|
|
```
|
|
|
|
### 校验逻辑
|
|
|
|
- 每次请求需携带 `Authorization: Bearer {token}`。
|
|
- 服务端验证签名、有效期（exp）、签发者（iss）及受众（aud）。
|
|
- 权限校验：中间件检查 `perms` 声明是否包含当前接口所需的权限。
|
|
|
|
***
|
|
|
|
## 4. 二次认证与会话提升 (Step-up)
|
|
|
|
针对高风险操作（如 `sync:write`、`policy:write`），要求会话必须处于“提升状态”。
|
|
|
|
### 流程设计
|
|
|
|
1. **触发**: 客户端调用 `/sync`，服务端检查 Token 的 `isStepUp` 声明。
|
|
2. **拒绝**: 若 `isStepUp == false`，返回 `403 SECOND_FACTOR_REQUIRED`。
|
|
3. **挑战**: 客户端调用 `/auth/step-up`，提供二次认证凭据（如再次输入密码，或 TOTP 验证码）。
|
|
4. **提升**: 验证成功后，服务端颁发一个新的 Token，其中 `isStepUp: true`，且有效期较短（如 30 分钟）。
|
|
5. **重试**: 客户端携带新 Token 重新发起请求。
|
|
|
|
***
|
|
|
|
## 5. 安全策略 (Security Policy) 存储与下发
|
|
|
|
安全策略决定了客户端的“落盘”行为及二次认证频率。
|
|
|
|
### 策略定义 (SecurityPolicies 表)
|
|
|
|
- `Id`: `int` (主键)
|
|
- `UserId`: `Guid` (外键)
|
|
- `AllowPersist`: `bool` (是否允许客户端持久化任务数据)
|
|
- `AllowSync`: `bool` (是否允许该用户同步)
|
|
- `SecondFactorExpiryMinutes`: `int` (二次认证状态保持时长，默认 30)
|
|
- `IsTrustedDeviceOnly`: `bool` (是否仅限受信任终端)
|
|
|
|
### 下发逻辑
|
|
|
|
- 客户端通过 `GET /security/policy` 获取。
|
|
- 策略应与 `UserId` 绑定，允许管理员针对不同用户/角色进行差异化配置。
|
|
|
|
***
|
|
|
|
## 6. 审计日志 (Audit Logs)
|
|
|
|
记录关键安全事件，便于追溯。
|
|
|
|
- 登录成功/失败（记录 IP、终端信息）。
|
|
- 高风险操作尝试（是否通过二次认证）。
|
|
- 安全策略变更。
|
|
|
|
***
|
|
|
|
## 8. 客户端 UI 与交互设计
|
|
|
|
### 8.1 二次认证 (Step-up) 交互流程
|
|
|
|
1. **静默拦截**: 当用户触发高风险操作（如点击“立即同步”且 Token 已过期或未提升）时，客户端拦截请求并检测到 `403 SECOND_FACTOR_REQUIRED`。
|
|
2. **弹出对话框**: 弹出“安全验证”模态框。
|
|
- **标题**: 需要二次认证。
|
|
- **描述**: “为了保护您的数据安全，执行此操作需要验证身份。”
|
|
- **输入**: 密码输入框（或 TOTP 验证码输入框）。
|
|
- **操作**: \[取消] \[验证并继续]。
|
|
3. **状态保持**: 验证成功后，UI 应显示短暂的“验证成功”提示，并自动重试刚才被拦截的操作。
|
|
|
|
### 8.2 客户端 UI (针对普通用户)
|
|
|
|
在客户端“设置 -> 云同步 -> 安全”路径下：
|
|
|
|
- **落盘策略 (AllowPersist)**:
|
|
- **展示**: 状态开关（Toggle）。
|
|
- **交互**:
|
|
- 若由服务端强制禁止，开关应为禁用状态（Disabled），并附带说明：“受服务端策略限制，当前终端禁止落盘”。
|
|
- 若允许修改，关闭开关时应弹出强提醒：“关闭后，所有本地任务数据将被立即清除，退出应用后数据将不再保留。确定继续吗？”
|
|
- **二次认证频率**:
|
|
- **展示**: 显示当前二次认证的有效期（如 30 分钟）。
|
|
|
|
### 8.3 “不可落盘”模式下的视觉提示
|
|
|
|
当 `allowPersist == false` 时：
|
|
|
|
- **状态栏/标题栏**: 增加“无痕模式”或“内存存储”小图标/文字提醒。
|
|
- **登录页**: 增加提醒：“当前环境配置为禁止落盘，数据仅在本次运行期间有效”。
|
|
- **退出应用**: 点击退出时，若有未同步数据，强提醒：“数据未同步且本地禁止落盘，退出将导致数据丢失。确定退出吗？”
|
|
|
|
***
|
|
|
|
## 9. 服务端管理后台 (Admin Dashboard)
|
|
|
|
为了避免直接操作数据库，服务端需提供一套 Web 管理后台，供管理员维护账户、权限与安全策略。
|
|
|
|
### 9.1 工程位置与实现
|
|
|
|
- **宿主项目**: [Hua.Todo.Host](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Host)
|
|
- **实现方式**:
|
|
- 前端采用 **Vue 3 + Vite** 开发。
|
|
- 静态资源在构建后嵌入到 `Hua.Todo.Host` 的 `wwwroot` 目录或作为内嵌资源。
|
|
- 后端通过 ASP.NET Core 的 `UseStaticFiles()` 托管，并确保 `/admin` 路由指向前端入口。
|
|
|
|
### 9.2 系统初始化 (Bootstrap)
|
|
|
|
- **触发条件**: 当检测到数据库中无任何用户时，访问 `/admin` 自动跳转至 `/admin/bootstrap`。
|
|
- **功能**: 创建首个“超级管理员”账号。
|
|
- **UI**: 简单的表单（用户名、密码、确认密码）。
|
|
|
|
### 9.3 用户管理 (User Management)
|
|
|
|
- **用户列表**: 展示所有已注册用户（UserId, UserName, Role, CreatedAt）。
|
|
- **创建用户**: 管理员手动添加用户（用于内部系统或受控注册）。
|
|
- **重置密码**: 为忘记密码的用户生成临时密码或直接重设（需审计记录）。
|
|
- **禁用/删除**: 软删除或禁用账号。
|
|
|
|
### 9.4 安全策略配置 (Security Policy Management)
|
|
|
|
- **全局策略**: 设置系统默认的 `allowPersist`、`allowSync` 及 `SecondFactorExpiry`。
|
|
- **单用户覆盖**: 在用户详情页中，管理员可以针对特定高风险用户/终端覆盖全局策略（例如：对特定外包人员账号强制 `allowPersist = false`）。
|
|
|
|
### 9.5 会话与凭据管理 (Session Management)
|
|
|
|
- **在线会话查看**: 展示当前所有有效的 Token/会话（记录 IP、最后活跃时间、是否已提升权限）。
|
|
- **强制下线 (Revoke)**: 管理员可一键吊销特定用户的所有 Token（将其加入黑名单）。
|
|
|
|
### 9.6 审计日志查看器 (Audit Log Viewer)
|
|
|
|
- **过滤查询**: 按时间、用户、事件类型（登录、同步、策略变更）过滤。
|
|
- **高亮显示**: 对“二次认证失败”、“异常 IP 登录”等敏感事件进行红色高亮。
|
|
|
|
***
|
|
|
|
## 10. 约束与风险
|
|
|
|
- **Token 吊销**: 默认 JWT 是无状态的。若需支持强制下线，需引入 Redis/DB 黑名单。
|
|
- **HTTPS**: 所有安全通信必须基于 TLS，防止中间人攻击窃取 Token。
|
|
- **暴力破解**: 需在 `POST /auth/login` 接口增加限流（Rate Limiting）机制。
|
|
|