一套可本地部署、职责分离、全程可追责的口令认证基线系统。
AuthBaseline 是一套完整的口令认证参考实现,覆盖认证系统的完整生命周期:注册审核、 登录、口令复杂度校验与哈希存储、失败锁定、会话票据、基于角色的访问控制(职责分离), 以及基于哈希链的审计日志。后端为 ASP.NET Core(.NET 8)+ MongoDB,前端是 Vue 3 的桌面形态应用,并可通过 Tauri v2 打包为 Windows 桌面软件。
它适合作为新系统的认证起点,也可作为认证与审计安全设计的参考实现:全部能力都可 在本机跑起来、可复算、可验证,不依赖任何外部服务。
各能力模块都有独立文档,本 README 覆盖整体架构、接口清单与运行方式:
| 文档 | 内容 |
|---|---|
docs/guides/DESKTOP-README.md |
桌面端使用与打包:Tauri v2 + Vue 3 + .NET sidecar,输出 Windows 安装包 |
docs/guides/EMAIL-VERIFY-README.md |
邮箱验证码:注册邮箱绑定、忘记密码重置 |
docs/design/ROLE-SEPARATION-DESIGN.md |
角色分离(职责分离):管理用户与读取审计互斥 |
docs/design/AUDIT-UPGRADE-DESIGN.md |
审计追责设计:让所有安全事件可追溯 |
docs/design/TRANSPORT-STORAGE-SECURITY-DESIGN.md |
传输与存储安全设计:TLS、票据哈希化、口令 pepper |
docs/design/ZOMBIE-ACCOUNT-GOVERNANCE-DESIGN.md |
沉睡账号治理:90 天自动冻结,可解冻、绝不删除 |
docs/design/FACE-AUTH-DESIGN.md |
人脸识别:账号级可选的登录第二因子(活体动作挑战、模板加密存储、fail-closed) |
docs/reports/AUDIT-VERIFY-REPORT.md |
审计哈希链的独立复算与验证报告 |
docs/reports/CODE-QUALITY-REPORT.md |
代码质量审计报告与整理路线 |
- 后端:ASP.NET Core Web API(.NET 8)—— 可用 Visual Studio 2022 或 .NET CLI 开发
- 数据库:MongoDB(推荐搭配 MongoDB Compass 直接观察数据)
- 前端:Vue 3(Composition API + Pinia + Vite),Tauri 封装的桌面软件形态 UI
- 密码哈希:BCrypt
- 人脸识别(可选的登录第二因子):OpenCvSharp —— YuNet 人脸检测 + SFace 特征,动作挑战活体
前端最初是原生 HTML + CSS + JavaScript 实现,后重构为 Vue 3 单文件组件应用, 呈现为桌面软件形态(标题栏 / 侧边栏 / 状态栏 / 可拖拽对话框 / 任务栏)。 后端接口与业务逻辑保持不变,旧版前端保留在
AuthClient/legacy-wwwroot/以便对照。
AuthBaseline/
├── AuthBaseline.sln # 解决方案文件(Visual Studio 2022 / dotnet CLI)
├── AuthServer/ # 后端(ASP.NET Core)
│ ├── AuthServer.csproj
│ ├── Program.cs # 服务注册、中间件、CORS、静态文件
│ ├── appsettings.json # MongoDB 连接字符串
│ ├── Controllers/
│ │ ├── AuthControllerBase.cs # 共享基类:票据鉴权、权限守卫、锁定判定
│ │ ├── AuthController.cs # 登录 / 登出 / 传输层状态
│ │ ├── AccountController.cs # 注册 / 邮箱验证码 / 忘记密码 / 修改口令
│ │ ├── UserAdminController.cs # 审核 / 解锁 / 冻结 / 注销 / 建号 / 角色任免
│ │ └── AuditController.cs # 审计查询、分片、统计、哈希链校验
│ ├── Models/
│ │ ├── User.cs / Session.cs / EmailCode.cs
│ │ ├── AuditLog.cs # 审计实体 + 动作 / 结果 / 原因码收口
│ │ ├── ApiResponse.cs # 统一响应
│ │ ├── BusinessCodes.cs # 业务码收口(返给用户的那一套,刻意与审计码分离)
│ │ └── AuthDtos.cs # 请求 / 响应 DTO;另有 FaceDtos.cs / FaceTemplate.cs
│ ├── Services/
│ │ ├── MongoDbService.cs # MongoDB 连接与管理员种子
│ │ ├── AuditService.cs # 审计写入、分片轮转、哈希链
│ │ ├── AuditWriter.cs # 审计写入的唯一出口(自动补齐来源 IP / UA)
│ │ ├── SessionService.cs # 会话票据签发 / 校验 / 吊销
│ │ ├── PasswordHasher.cs # 口令哈希唯一出口(pepper + BCrypt)
│ │ ├── PepperProvider.cs # 本机 pepper 的 DPAPI 存取(另有 PepperCli.cs)
│ │ ├── TicketHasher.cs # 票据哈希(无盐 SHA-256 + Base64Url)
│ │ ├── TimeGuard.cs # 时钟护栏:墙钟 + 单调时钟双线判定
│ │ ├── CertificateManager.cs # 本机私有 CA 与 leaf 证书
│ │ ├── DormantAccountService.cs # 沉睡账号判定与冻结
│ │ ├── Face/ # 人脸第二因子:引擎抽象 / OpenCvSharp 实现 / 模板加密存储 / 挑战一次性票据
│ │ └── EmailSender.cs / VerificationService.cs / EmailOptions.cs
│ ├── face-models/ # YuNet 检测 + SFace 识别 ONNX 模型(随产物分发,含上游许可证)
│ └── wwwroot/ # 前端构建产物(由 AuthClient 构建生成)
├── AuthClient/ # 前端源码(Vue 3)
│ ├── package.json
│ ├── vite.config.js # 开发代理 /api → 5007;两种 mode 决定产物输出目录
│ ├── smoke_test.py # 端到端接口冒烟测试(26 项)
│ ├── legacy-wwwroot/ # 旧版原生前端备份
│ └── src/
│ ├── main.js
│ ├── App.vue # 桌面外壳:窗口/最小化/最大化/关闭/壁纸/任务栏
│ ├── styles/ # 设计令牌、基础样式、表单共享样式
│ ├── api/client.js # API 封装与错误分类
│ ├── composables/ # clock(全局心跳)/ poller(轮询工厂)/ useEmailCode
│ ├── stores/ # Pinia
│ │ ├── session.js # 会话状态 + 各角色域的组装根
│ │ ├── roles.js # 角色常量与显示标签
│ │ └── domains/ # auditDomain(审计域)/ adminDomain(用户管理域)/ faceDomain(人脸域)
│ ├── components/ # 外壳与通用组件;auth/、users/、face/ 放表单与流程子组件
│ └── views/ # 登录、仪表盘、账号口令、用户管理、审计日志
├── docs/ # 设计、报告与指南
│ ├── design/ # 五份 *-DESIGN.md(角色分离 / 审计 / 传输存储 / 沉睡账号 / 人脸)
│ ├── reports/ # 审计链验证报告、代码质量报告
│ └── guides/ # 桌面端打包、邮箱验证码使用指南
├── tools/ # 验证与运维脚本(分类索引见 tools/README.md)
└── README.md
- 安装并启动 MongoDB(默认端口
27017)。 - 可选:安装 MongoDB Compass,连接
mongodb://localhost:27017,数据库名为AuthBaselineDb。 - 安装 .NET 8 SDK,然后任选一种方式打开工程:
- Visual Studio 2022 打开
AuthBaseline.sln; - 或使用 .NET CLI(
dotnet build/dotnet run)。
- Visual Studio 2022 打开
- 首次打开后,NuGet 包会自动还原(MongoDB.Driver、BCrypt.Net-Next)。
- 可选:要用「纯人脸登录」还需下载 ArcFace 权重(174 MB,许可仅限非商业研究,不随仓库分发),
步骤与 sha256 见
AuthServer/face-models/README.md。 缺这个文件不影响其他功能 —— 只是纯人脸登录会 fail closed(人脸第二因子用的是 SFace,已随仓库提供)。
- 在 Visual Studio 2022 中,将
AuthServer设为启动项目(或执行dotnet run --project AuthServer)。 - 按
F5或Ctrl+F5运行。 - 浏览器打开
http://localhost:5007/。
后端 API 地址:
http://localhost:5007/api/auth/...前端产物已构建并提交在
AuthServer/wwwroot/,直接运行后端即可看到界面, 无需启动前端开发服务器。
⚠️ VS 默认使用的http启动配置走明文对照模式(自动设AUTHBASELINE_REQUIRE_HTTPS=false), 目的是让调试与既有脚本不受影响;要看加密形态请选https启动配置,或直接运行桌面端。 桌面端首次启动可能弹出一次 Windows 证书信任确认框,选「是」(写CurrentUser\Root, 不用管理员权限;产品化路径是安装期写LocalMachine\Root)。
只有需要修改界面时才需要走这一步:
cd AuthClient
npm install # 首次
npm run dev # 开发服务器 http://localhost:5173,/api 自动代理到 5007
npm run build # 只出浏览器产物 → ../AuthServer/wwwroot改完界面建议用
python tools/build_all.py frontend统一构建。本项目有两条分发链路,靠 vite 的 mode 区分输出目录:
链路 产物目录 构建命令 浏览器访问(后端静态托管,同源 /api)AuthServer/wwwrootnpm run build桌面端(Tauri 打包 / 热替换安装目录) AuthClient/distnpm run build:desktop只跑其中一条命令,另一条链路的产物就会停在旧版本 —— 本项目出过一次
wwwroot落后dist15 天、浏览器打开后端看到旧界面的事故。 上面的脚本会两套都构建,并逐字节比对两者是否一致,不一致直接报非零退出码。单独做一致性检查(不构建):
python tools/build_all.py check
系统首次启动时会自动创建:
- 用户名:
admin - 密码:
Admin123
⚠️ 这是公开的默认种子口令,仅用于首次进入系统。请在任何非本机环境部署前修改, 或通过set-role/create-account接口建立自己的管理员账号后停用默认账号。
- 普通用户注册后状态为 待审核(Pending),无法登录。
- 管理员在“管理员控制台”点击“通过”后,状态变为 启用(Enabled)。
- 至少 8 位
- 同时包含大写字母、小写字母、数字
示例合法密码:Hello123、Admin123、Password1
- 用户密码通过 BCrypt 哈希后存入 MongoDB。
- 数据库中只保存
passwordHash,不保存明文。 - 当前实现为 pepper + BCrypt + 内嵌盐(
v2$前缀),旧格式哈希在登录时自动升级。 详见 docs/design/TRANSPORT-STORAGE-SECURITY-DESIGN.md。
- 3 分钟窗口内输错 3 次 密码,账号状态变为 锁定(Locked)。
- 锁定持续 3 分钟。
- 锁定期间即使输入正确密码,也拒绝登录。
- 3 分钟后系统自动解锁;或管理员可手动解锁。
关于"3 分钟窗口"的口径,有两点需要说清(它直接决定演示时的预期结果):
| 情形 | 结果 |
|---|---|
| 错 → 错 → 错(三次都落在窗口内) | 第 3 次即锁定 |
| 错 → 等超过 3 分钟 → 错 | 不锁:首个窗口已过期,计数归零,这一次是新窗口的第 1 次 |
| 锁定期间再试(含正确密码) | 一律拒绝,且不累加失败计数 |
- 规则是「从第一次失败起算 3 分钟」:窗口内累计满 3 次即锁,窗口一过计数归零重来。 因此计数不是终身累计 —— 慢慢试是试不出锁定的,连续爆破与稀疏尝试的判定结果不同。
- 计数窗口与锁定判定同样记录墙钟与单调时钟两个锚点,偏离超过容差以单调时钟为准。 这一条不是可选项:窗口过期等于"重新拿回 3 次机会",若只按墙钟判, 攻击者每次错 2 次就把系统时间拨快 3 分钟即可让窗口作废、永不锁定。
- 拨动时钟这件事本身会留痕:锁定判定期内发现背离写入
CLOCK_ANOMALY; 尚未锁定时(失败计数窗口内)发现背离同样写入 —— 否则攻击者在 3 次尝试之内拨钟 会完全静默,事后翻审计看不到任何记录。 - 这份留痕只用于取证,不改变判定:拨钟既不会让计数提前作废(拿不到额外机会),
也不会让账号被提前锁定。能改系统时钟的人本机已持有管理员权限(需要
SeSystemtimePrivilege), 给他加罚只会误伤普通人 —— 所以加固的目标始终是"右键改时间"这条最廉价的路径。
- 登录后可在用户面板修改密码。
- 修改成功后,旧密码立即失效,旧会话票据同时吊销。
- 管理员可在用户列表点击「注销」删除账号,操作前会弹窗二次确认,防止误删。
- 处置范围随操作者身份而定(判定集中在
UserRoles.CanBeManagedBy):Admin—— 除自己以外任意账号都能注销,含审计管理员与其它管理员;UserAdmin—— 只能注销普通用户与用户管理员,够不到审计管理员与管理员。
- 任何角色都不能注销自己,避免系统里最后一个能任命角色的账号被删掉。
- 注销会写入审计日志,
statusAfter记为Deleted,且不可逆(数据库中不存在回收站集合)。
- 判定基准是
lastLoginAt(缺失时回退createdAt),超过阈值(默认 90 天)未登录即视为沉睡。 - 处置方式是冻结(置
Disabled)而不是删除(红线:绝不删除账号),可由用户管理员 通过/api/auth/unlock解冻。 - 管理账号默认排除自动判定,防止权力真空;命中时审计记
DORMANT_PROTECTED_ROLE。 - 判定时间源走
TimeGuard.WallNow(),可在演示时通过修改系统时间验证。 - 详见 docs/design/ZOMBIE-ACCOUNT-GOVERNANCE-DESIGN.md。
每个关键操作都会在 MongoDB 审计集合中记录:
operatorId/operatorName:操作者action:动作(Login/Register/Approve/Unlock/DeleteUser/ChangePassword/FreezeUser/SetRole/AuditVerify/AuditAccessDenied…)result:结果(Success/Failed)reasonCode:失败原因码(如WrongOldPassword/InvalidCredentials/AccountLocked/PasswordReused/ClockAnomaly),用于检索弱口令与口令猜测等事件statusBefore/statusAfter:操作前后的账号状态request/response:请求与响应内容(已脱敏,不含口令)timestamp:UTC 时间;seq/selfHash/prevHash:哈希链字段
成败按动作分开记录(如
LoginSuccess与LoginFailed),失败项必带reasonCode。 审计写入属旁路:写不进去也绝不阻断登录、改密等主流程。
⚠️ 防篡改口径:这是无密钥的 SHA-256 链(非 HMAC),只保证「局部增删改会留下无法 局部修补的断点」,可用tools/verify_chain_independent.py独立复算, 不等价于「不可篡改」。
日志按 AuditLogs_yyyyMM 分片存储,每条带 selfHash / prevHash / seq 构成哈希链,
分片头部锚点记录在 AuditChainHeads,可通过 GET /api/audit/verify 校验完整性。
前端以桌面软件的形态呈现,而不是普通网页:
| 元素 | 行为 |
|---|---|
| 标题栏 | 应用标识、主题切换(浅色/深色)、最小化 / 最大化 / 关闭 |
| 侧边栏 | 功能导航(仪表盘、账号与口令、用户管理、审计日志),待审核数量角标 |
| 状态栏 | 后端连通状态、传输加密指示、上次同步时间、锁定倒计时、当前用户、系统时钟 |
| 任务栏 | 最小化后可从任务栏恢复;关闭后桌面上保留图标,双击重新打开 |
| 子窗口 | 注销确认、日志详情为可拖拽对话框,Esc 关闭 |
| 通知 | 右上角应用内 Toast,按成功/错误/警告/信息分色 |
无障碍与规范:全矢量内联图标(无 emoji 充当图标)、表单均有标签与行内错误提示、
焦点可见、prefers-reduced-motion 下自动关闭动效、深浅双主题均满足文本 4.5:1 对比度。
人脸是账号级可选的第二因子,不录入完全不影响使用 —— 管理员账号默认不录入,也没有任何 需要人脸才能使用的功能。三条产品规则:
| 人群 | 行为 |
|---|---|
| 已注册用户 | 可在「账号与口令」页自助选择添加人脸(需重新输入当前口令) |
| 新注册用户 | 注册流程中可以选择是否导入人脸 |
| 所有管理员 | 不添加人脸,也不受任何影响 |
两步登录:口令通过后,若该账号已录人脸,/api/auth/login 不签发票据,只返回
FACE_REQUIRED 与一次性挑战;人脸通过后才由同一出口签发票据。人脸响应里没有画面或特征 ——
采集端在服务端(否则攻击者可直接 POST 一个伪造的特征向量进来)。
- 活体动作挑战:随机要求转头/抬头/低头,凭一次性挑战 token 完成,用途绑定(录入挑战不能拿去登录)。
- 识别画面(取景框):录入与刷脸时会显示实时画面 —— 画面由服务端采集、检测并画好框之后
逐帧下发,前端不接触摄像头设备、也不上送任何画面或特征。取画面的门禁绑在那张一次性挑战上:
过期 / 被消费 / 采集结束即失效,不是一条谁都能拉的常开摄像头流。
⚠️ 口径(不说满):它仍落在未鉴权面(登录前没有票据可携带),缓解手段只有 "仅绑环回 + 挑战门禁"两条,且接口只出图像、不下发关键点坐标。不要宣称"摄像头不会被别人打开"。 - 模板加密存储:AES-256-GCM 可逆加密(人脸要能还原明文才能算余弦相似度,不是哈希), AAD 绑定用户 ID;绝不进审计、绝不导出;注销账号时连带真删,不留生物特征孤儿。
- fail-closed:已录人脸但本机引擎不可用 ⇒ 拒绝登录(503
FACE_ENGINE_UNAVAILABLE), 不会静默退回单因子 —— 否则"弄坏摄像头"会比"删模板"更廉价。恢复路径是管理员reset-face(两套人脸一起清:第二因子的模板与纯人脸登录的模板,各留一条审计)。 - 失败分流(A/B 组):欺骗类信号(比对不符、活体不过、挑战无效、口令错)计入锁定计数;
质量/配合类问题(未检测到人脸、画质太差、动作未完成)不计次 ——
用户不会被自己的摄像头误伤到锁号。规则钉在审计码上(
FaceCodes.IsCounted),未登记码兜底计入。 - 降级通道闸门:录入与删除人脸都必须重新输入当前口令,口令错误按 A 组计次。
⚠️ 口径(不说满):人脸模板是可逆加密存储,防的是"库文件被拿走", 防不了"进程被注入或调试器附加"。 详见 docs/design/FACE-AUTH-DESIGN.md。
与上面第 10 节的「第二因子」是两条独立链路:第二因子是「口令 + 人脸」,这一节是 「用户名 + 人脸」,全程没有口令参与。两者各自独立存储模板、各自一套特征模型,可以同时启用。 同样不录入就完全不影响使用。
| 项 | 说明 |
|---|---|
| 引擎 | YuNet(检测 640×480)+ ArcFace w600k_r50(512 维特征) |
| 判定 | 余弦相似度 ≥ 0.30 通过;[0.25, 0.30) 灰区(不签票、不计失败,提示改用口令);< 0.25 计一次失败 |
| 阈值来源 | LFW 正 3000 对 / 负 50000 对实测定档:0.30 ⇒ FAR 2e-5、TAR 98.30%(详见 P3 报告) |
| 模板 | 每人最多 3 张,AES-256-GCM 加密存独立集合;modelId 绑定引擎与权重 ⇒ 换模型后旧模板自动作废、如实告知 |
| 计次 | 只对「明确不是本人」「活体不过」计次;未录入 / 灰区 / 质量类 / 引擎类一律不计 |
- 登录顺序:空用户名 → 用户不存在(与「人脸不像」同码同话术,不给枚举额外信号)→ 锁定/禁用(均在采脸之前拒绝)→ 采集识别 → 签票或计次。
- 请求体只有用户名:没有画面、没有特征,采集在服务端进程内完成 —— 与第二因子同一条边界, 「伪造一个向量直接提交」这条路在类型层面就不存在。
- fail-closed:已录人脸但引擎不可用 ⇒ 503
FACEID_ENGINE_UNAVAILABLE,不会静默退回口令登录。 - 降级闸门:录入与删除都必须重新输入当前口令,口令错误按失败计次。
⚠️ 活体判定默认关闭。这不是遗漏:本模块要用「不同人种 / 明星各年龄段 / 双胞胎 / 特殊人群」的 照片样本做验收,而这些找不到真人,所以默认状态下举着照片就能通过。 需要反欺骗时设AUTHBASELINE_FACEID_PAD_ENABLED=true(内置 MiniFASNetV2,阈值 0.70); 多脸默认拒绝,测试照片时可设AUTHBASELINE_FACEID_ALLOW_MULTI_FACE=true放行并取最大框。 界面上只显示「录入状态 / 最近录入 / 判定阈值」三项,活体与多脸开关的真实状态请查启动日志。
⚠️ 口径:LFW 3000 对上 acc@0.5 = 96.83%、EER 1.87%、TAR@FAR=1e-4 = 97.93%。 这些是离线简单集(正脸、光照正常)上的数字,不是线上通过率,更不是 PAD 或识别认证的结论。
以下用例均已在开发机上实测验证,全部符合预期(实测记录见第十一章第 6 节)。
上面这些用例是给人看的;下面这些是给机器跑的,改动后先跑它们:
| 命令 | 覆盖 | 说明 |
|---|---|---|
dotnet test AuthServer.Tests/AuthServer.Tests.csproj |
210 项 | TimeGuard(锁定/窗口/拨钟边界)、PasswordHasher(v2$ 红线、升级标记、脏数据)、FacePose,以及 FaceId 的纯逻辑:FaceIdDecision(阈值 = 通过线的三途边界)、FaceIdQuality(闸门顺序)、FaceIdCodes(计次分流)、FaceIdOptions(默认值与覆盖)、活体分数边界。不连库、不碰摄像头 |
cd AuthClient && npm run lint |
0 error / 0 warning | 只开"真 bug 类"规则 |
python tools/privacy_scan.py --no-history --gate |
新增命中 0 | 只对 tools/privacy_baseline.json 之外的新增命中失败 |
python tools/face_fixture_check.py AuthServer/bin/Debug/net8.0/AuthServer.exe |
每个 fixture 一条 | 重放录制画面,比对 passed / businessCode(需先录,见下) |
四类都在 GitHub Actions 里跑(.github/workflows/ci.yml):后端编译+单测 / 前端 lint+构建 /
脱敏门禁 / 发布产物布局(模型不能被单文件打包器吞掉)。
需要真实库与真机的探针不进 CI —— 它们跑一次十几分钟且会写库,红着的门禁等于没有门禁。
人脸动作挑战的回归(需要摄像头,录一次即可反复用):
# 录:坐在摄像头前,按提示把头转向一侧再转回正对镜头
AuthServer/bin/Debug/net8.0/AuthServer.exe --face-record tools/fixtures/face/left-ok left
# 回放:不需要摄像头,输出 FACE_REPLAY_RESULT={...}
python tools/face_fixture_check.py AuthServer/bin/Debug/net8.0/AuthServer.exetools/fixtures/ 里是真人的脸,已在 .gitignore 中,不要提交。
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | 注册普通用户 alice,密码 Hello123 |
注册成功,状态为 Pending |
| 2 | 用 admin / Admin123 登录 |
登录成功,进入管理员控制台 |
| 3 | 管理员审核通过 alice |
alice 状态变为 Enabled |
| 4 | 用 alice / Hello123 登录 |
登录成功 |
| 5 | alice 修改密码为 World456 |
修改成功 |
| 6 | 用 alice / World456 登录 |
登录成功 |
| 7 | 用 alice / Hello123 登录 |
旧密码失效,登录失败 |
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | 注册重复用户名 alice |
拒绝,提示“用户名已存在” |
| 2 | 使用错误旧密码修改密码 | 拒绝,提示“旧密码错误” |
| 3 | 输入空用户名/空密码 | 拒绝,提示字段不能为空 |
| 4 | 注册密码 123 |
拒绝,提示密码复杂度不足 |
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | 连续 3 次用 alice / 错误密码 登录 |
第 3 次后账号锁定 |
| 2 | 锁定期间用 alice / 正确密码 登录 |
拒绝,提示账号锁定 |
| 3 | 3 分钟后再次用正确密码登录 | 登录成功(自动解锁) |
| 4 | 或管理员手动点击“解锁” | 立即解锁,可用正确密码登录 |
| 5 | 错 2 次 → 停止操作 3 分钟以上 → 再错 1 次 | 不锁定,提示「还剩 2 次机会」(窗口已过期,计数从 1 重开) |
| 6 | 错 2 次 → 把系统时间前拨 3 分钟 → 再错 1 次 | 仍然锁定(窗口按单调时钟判,拨钟不能让它提前作废) |
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | 把系统时间前拨 90 天以上,刷新用户列表 | 长期未登录账号出现在「沉睡候选」 |
| 2 | 对候选账号点「冻结」 | 置为 Disabled,登录被拒(ACCOUNT_DISABLED),账号未删除 |
| 3 | 用户管理员点「解除冻结」 | 恢复 Enabled,可正常登录 |
| 4 | 对比管理账号 | 不参与自动判定,审计记 DORMANT_PROTECTED_ROLE |
更多自动化验证脚本见
tools/:角色分离(role_separation_test.py)、 时间回拨(lockout_clock_probe.py)、票据哈希化(ticket_hash_probe.py)、 口令 pepper(pepper_probe.py)、沉睡账号(dormant_account_probe.py)、 用户管理批量处置(batch_action_probe.py)、 审计链独立复算(verify_chain_independent.py)。 完整清单与分类索引见tools/README.md。
打开 MongoDB Compass,查看 AuthBaselineDb 数据库:
Users集合:观察status、failedLoginAttempts、lockoutEnd字段变化, 以及沉睡治理用到的lastLoginAt/dormantFrozenAt。AuditLogs_yyyyMM集合:按月分片的审计日志,观察每次操作的状态流转证据。AuditChainHeads集合:哈希链的头部锚点。Sessions集合:会话票据(只存哈希,看不到明文票据)。EmailCodes集合:邮箱验证码(带有效期与使用标记)。FaceTemplates集合:人脸特征模板(密文,含 nonce / tag / 维度;明文特征只在本机内存中短暂存在)。
典型的状态流转链:
待审核(Pending) → 启用(Enabled) → 锁定(Locked) → 启用(Enabled)
↘ 冻结(Disabled) → 启用(Enabled)
本项目没有
DeletedUsers之类的回收站集合 —— 注销不可逆,这是刻意的设计而非遗漏。
下表为后端当前实际暴露的全部接口(共 28 个)。 鉴权自「角色分离」改造起改为服务端签发的 Bearer 票据(
Authorization: Bearer <ticket>), 不再使用早期的?adminUsername=xxx由客户端自证身份的方式。 鉴权失败会写入一条AUDIT_ACCESS_DENIED事件,使越权尝试可追溯。控制器按业务域拆分(
AuthController/AccountController/UserAdminController/AuditController/FaceIdController,共享基类AuthControllerBase),但路由路径一字未变 —— 拆分只动文件边界,不动对外契约。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | /api/auth/login |
匿名 | 用户登录,成功返回会话票据。若该账号已录入人脸,此处不签发票据,改为返回 FACE_REQUIRED 与一次性挑战 |
| POST | /api/auth/login/face |
匿名(凭挑战) | 人脸第二因子:请求体只有一次性挑战 token,不含画面或特征(采集在服务端完成),通过后才签发票据 |
| POST | /api/auth/logout |
需票据 | 注销当前会话(吊销票据) |
| GET | /api/auth/transport |
匿名 | 传输层状态:当前链路是否加密(TLS)、证书主题与到期日。刻意不做鉴权 —— 状态栏在登录页就要显示,且内容属于公钥信息 |
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | /api/auth/register |
匿名 | 用户注册(校验邮箱验证码,创建后状态为待审核) |
| POST | /api/auth/send-email-code |
匿名 | 发送邮箱验证码(注册与重置口令共用);对不存在的邮箱返回与真实发信逐字一致的响应,防账号枚举 |
| POST | /api/auth/reset-password |
匿名(凭验证码) | 忘记密码:校验邮箱验证码后直接设置新口令 |
| POST | /api/auth/change-password |
需票据 | 修改自己的口令;新旧口令不得相同 |
人脸是账号级可选的登录第二因子。不录入人脸的账号(含全部管理员)行为与改造前逐字一致, 照常用口令登录。下面 4 条自助接口都需要票据;其中录入、删除都必须重新输入当前口令作为降级通道闸门。 最后一条(识别画面)是匿名的例外,它的凭据是一张一次性挑战,不是票据。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/auth/face |
需票据 | 查询自己的人脸状态(是否已录、模板数、引擎是否就绪)。只读,不写审计 |
| POST | /api/auth/face/enroll |
需票据 + 口令 | 录入人脸第一步:校验当前口令后签发一次性录入挑战 |
| POST | /api/auth/face/enroll/complete |
需票据(凭挑战) | 录入人脸第二步:凭挑战完成采集与入库;挑战用途绑定,不可挪用于登录 |
| POST | /api/auth/face/delete |
需票据 + 口令 | 删除自己的人脸模板(真删,不留可复原数据) |
| GET | /api/auth/face/preview |
匿名(凭一次性挑战) | 识别画面:返回一帧由服务端采集、检测并画好框的 JPEG(状态随 X-Face-State / X-Face-Score 响应头下发)。门禁绑在挑战上 —— token 过期 / 被消费 / 采集结束即失效;只出图像,不下发关键点坐标 |
与上一节的第二因子完全独立(不同集合、不同特征模型、不同控制器),可同时启用。 前 3 条自助接口需要票据,其中录入与删除都必须重新输入当前口令;最后一条是匿名的登录接口。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/faceid/status |
需票据 | 查询自己的录入状态(模板数 / 可用数 / 模型身份 / 判定阈值)。只读,不写审计 |
| POST | /api/faceid/enroll |
需票据 + 口令 | 录入:校验当前口令后单步采集(本模块无动作挑战),取第一张过闸门的帧入库 |
| POST | /api/faceid/delete |
需票据 + 口令 | 删除自己的人脸模板(真删,不留可复原数据) |
| POST | /api/faceid/login |
匿名 | 用户名 + 人脸登录。请求体 {"username": "..."},不含画面或特征;失败时回传 similarity 便于判断是光线还是脸不对 |
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/auth/users |
用户管理员 | 获取用户列表(含沉睡候选与受保护标记) |
| GET | /api/auth/dormant-users |
用户管理员 | 沉睡账号候选:超过阈值天数未登录、且角色不受保护的账号 |
| POST | /api/auth/approve |
用户管理员 | 审核通过待审核用户 |
| POST | /api/auth/unlock |
用户管理员 | 手动解锁被锁定的账号,也用于解除冻结(Disabled → Enabled) |
| POST | /api/auth/freeze-user |
用户管理员 | 冻结沉睡账号(置 Disabled),可解冻、绝不删除 |
| POST | /api/auth/delete-user |
用户管理员 | 注销普通用户(管理员账号不可被注销) |
| POST | /api/auth/create-account |
管理员 | 创建普通用户 / 用户管理员 / 审计管理员(不可建 Admin);邮箱可选,需二次校验操作者口令 |
| POST | /api/auth/set-role |
管理员 | 任免用户角色(含 AuditAdmin),需二次校验操作者口令 |
| POST | /api/auth/reset-face |
用户管理员 | 重置指定账号的两套人脸(第二因子模板 + 纯人脸登录模板),用于本人丢失人脸后的恢复;两条链路各写一条审计(FACE_TEMPLATE_RESET / FACEID_TEMPLATE_RESET);复用既有 CanBeManagedBy 授权出口(含自我豁免) |
| POST | /api/auth/batch |
用户管理员 | 批量处置:action ∈ approve / unlock / freeze / delete / reset-face / set-role,usernames 为目标列表(上限 200)。内部逐条调用上方单条入口,因此权限、自我豁免、审计语义与单条完全一致;部分成功是正常结果,逐条返回 success / code / message。业务码:全部处理完 OK、有成功有失败 BATCH_PARTIAL、一个都没处理 BATCH_ALL_FAILED(400)。逐条判定不整批放行,set-role 仍要求操作者口令且仅 Admin 可用 |
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/audit/logs |
审计读 | 分页查询审计日志,支持按分片 / 关键词 / 动作 / 结果筛选 |
| GET | /api/auth/logs |
审计读 | 兼容旧路径,内部转调同一套分页逻辑 |
| GET | /api/audit/verify |
审计读 | 哈希链完整性校验,返回断点序号与所在分片 |
| GET | /api/audit/shards |
审计读 | 分片清单与各片规模 |
| GET | /api/audit/stats |
审计读 | 概览统计:总数、失败数、篡改告警数 |
| GET | /api/audit/sod |
审计读 | 职责分离绕过线索:把「管理员造出审计管理员再借它读日志」还原成可枚举的归因链(见 角色分离设计 §4.6) |
⚠️ 审计域没有任何写接口。控制器只暴露上述 6 个 GET(其中sod是只读推导,不写库),后端不存在删除或修改审计 日志的路径;界面上的「重置筛选」只是清空查询条件,与日志本体无关。
角色为互斥枚举,避免出现非法权限组合:
| 角色 | 管理用户 | 分配角色 | 读取审计 |
|---|---|---|---|
User |
— | — | — |
UserAdmin |
仅普通用户 | — | — |
Admin |
✓ | ✓(含 AuditAdmin) | — |
AuditAdmin |
— | — | ✓ |
职责分离:Admin 能管理用户与分配角色,但不能读取审计日志;AuditAdmin
能读取审计日志,但不能管理用户。两者权限互斥,任何单一角色都无法同时篡改数据与
掩盖痕迹。
账号创建入口:建号只有 Admin 能做(UserAdmin 能管账号但不能造账号),
可建 User / UserAdmin / AuditAdmin,不能建 Admin(不允许管理员自我复制)。
邮箱在创建时可选:留空即只凭口令登录(登录标识是用户名、不是邮箱,所以照样能登),
代价是该账号用不了「忘记密码」;填写则登记为已验证,随后即可自助找回密码。
- 用户名统一转小写并去除首尾空格,避免大小写重复。
- 口令复杂度由服务端裁决并留痕:前端不做提交门禁,否则「反复提交弱口令」这类 安全事件在后端完全看不见。
- 所有写操作均记录审计日志,便于追溯攻击与异常。
- 锁定状态优先于口令校验,确保暴力破解期间即使撞对口令也无法进入。
- 锁定期同时记录墙钟与单调时钟(
Environment.TickCount64),偏离超过容差时以单调时钟 为准并写CLOCK_ANOMALY—— 回拨系统时间这条最廉价的绕过路径被堵死且留痕 (口径:堵死且留痕,不是「不可绕过」)。 - 口令哈希使用 BCrypt(自适应成本,抗彩虹表),外层再叠 pepper(存于本机 DPAPI 保护的文件)。
- 响应使用统一格式
{ success, code, message, data },前端易于处理。 - 审计日志写入做了异常兜底:日志记录失败不会阻断注册/登录等主流程。
- 数据库中的会话票据只保存哈希(无盐 SHA-256 + Base64Url),明文票据仅在签发时返回一次。
- 防账号枚举:
send-email-code对不存在的邮箱返回与真实发信逐字一致的响应, 而审计侧仍如实记为失败。
第一步先确认后端是否在运行(最常见的原因):
- 在 VS2022 中按
F5启动AuthServer,或命令行执行dotnet run。 - 浏览器访问
http://localhost:5007/,打不开就说明后端没跑起来。 - 界面左下角状态栏会实时显示「后端已连接 / 后端未连接」。
前端已把错误分成三类,便于快速定位:
| 提示 | 含义 |
|---|---|
| “无法连接后端服务。请确认 MongoDB 已启动…” | 后端进程没运行,或端口不对 |
| “服务器返回 HTTP 500” | 后端内部异常,查看 VS 输出窗口的异常堆栈 |
| 具体中文提示(如“密码必须至少8位…”) | 业务逻辑正常拦截,按提示修改输入即可 |
- MongoDB Compass 只是客户端,不自带数据库服务,必须另外启动 MongoDB Server,
默认监听
127.0.0.1:27017。 - 数据库名为
AuthBaselineDb,集合为Users、Sessions、EmailCodes、AuditLogs_yyyyMM(按月分片)与AuditChainHeads。 - 只有后端成功启动并收到请求后才会写入数据。首次启动会自动建唯一索引并预置管理员
admin(MongoDbService是懒构造:迁移发生在第一个真正触库的请求上)。 - Compass 里看不到时,点一下刷新按钮。
AuditLog 的 request / response 字段若声明为 object,MongoDB 的
ObjectSerializer 会拒绝序列化 ApiResponse<T> 这类自定义类型,抛出
BsonSerializationException,导致整个请求返回 500。
典型症状:用户数据其实已经写进 Users 集合,但接口返回 500,前端只能显示兜底的“注册失败”。
本项目已改为 string(写入前用 JsonSerializer.Serialize 序列化成 JSON 字符串),
并对日志写入加了 try-catch —— 审计日志属于旁路记录,失败绝不能拖垮主流程。
最常见的原因是数据库里的用户文档带了当前版本不认识的字段:C# 驱动的模型绑定遇到
未知字段会抛 FormatException(不忽略),于是在管理员种子阶段就失败,
连不需要鉴权的 /api/auth/transport 也会 500。
典型触发场景:换了新版本的库,却还在跑旧版编译产物。处置方式是重新发布并 安装当前版本,不要靠改库去迁就旧二进制。
若 5007 被占用,修改 AuthServer/Properties/launchSettings.json 中的
applicationUrl 即可。
以下流程已用 curl 实测全部通过:
| 场景 | 结果 |
|---|---|
| 注册合规密码 | 200,状态 Pending |
注册弱密码 123 |
400,WEAK_PASSWORD |
| 未审核账号登录 | 401,PENDING_APPROVAL |
| 管理员登录 / 审核通过 | 200,状态转 Enabled |
| 连续 3 次错误密码 | 401,锁定并写入 lockoutEnd |
| 锁定期间输入正确密码 | 401,ACCOUNT_LOCKED(核心要求达成) |
| 管理员解锁 | 200,Locked → Enabled,失败次数清零 |
| 修改密码 | 200,旧密码立即失效 |
| 审计日志落库 | 含 statusBefore/After、operatorId、时间戳 |
先看 AuthServer/face-models/ 里有没有 face_recognition_arcface_w600k_r50.onnx ——
这个权重不入库(174 MB,许可仅限非商业研究),需按该目录下 README.md 自行下载并核对 sha256。
缺文件时:/api/faceid/status 报 engineReady=false,登录与录入一律 503(fail closed);
而人脸第二因子仍然可用(它用 SFace,已随仓库提供)。这是两个模块刻意不共用的结果,不是故障。
欢迎 issue 与 pull request。
报告问题:请附上复现步骤、期望行为与实际行为,以及环境信息(.NET 版本、MongoDB
版本、是否桌面端)。与审计链、口令存储或传输层相关的现象,请一并给出对应的审计
reasonCode 或错误码。
提交代码:
- Fork 本仓库并从
main切出特性分支(如feat/session-rotation)。 - 一个提交聚焦一件事,提交信息使用 Conventional Commits 前缀
(
feat/fix/docs/test/chore),并在正文说明动机与影响面。 - 改动涉及前端时,请用
python tools/build_all.py frontend构建并确认两条产物链路 逐字节一致;涉及接口或权限模型时,请跑一遍tools/下对应的验证脚本。 - 发起 PR,描述变更内容、验证方式与已知限制。
安全漏洞:请勿通过公开 issue 披露。审计链、口令存储、传输层与权限模型均属于 安全敏感面,请私下联系维护者并给出一段可复现的说明。
本项目基于 MIT License 发布,版权所有 (c) 2026 Ruiyan Diao。