UniSSO 是整个集市的账号中心:注册、登录、扫码、二次验证、会话与设备管理、OAuth2/OIDC 授权、应用注册与审核,都收在这一个服务里。后端是 C++20 + cpp-httplib(backend/src 约 1.3 万行),会话存 Redis,内部令牌用 HMAC JWT,对外 OIDC 用 RSA 并通过 JWKS 暴露公钥;前端 Vue 3。这篇讲认证主流程,以及几个一旦写错就会变成安全事故的细节。
注册与验证码
注册是「填邮箱 → 收 6 位验证码 → 设密码 → 验证后可用」。验证码不落明文:落 Redis 前用服务端密钥做 HMAC-SHA256,待注册记录按邮箱摘要建键。发送频率做双限流,同一邮箱每小时一个上限,同一 IP 每小时一个上限。提交后先进入待验证态,验证通过才建正式用户。路由集中在 backend/src/app/routes.cpp:POST /api/auth/register、/api/auth/verify-email、/api/auth/resend-registration。
1 | // backend/src/app/registration.cpp |
两个坑。第一,验证码比对要「哈希后常数时间比较」:直接比明文,Redis 泄露等于验证码泄露;用普通 == 比较,理论上有时序侧信道。第二,限流键用邮箱摘要:写原文会把全站邮箱暴露在 Redis 键名里,运维一条 KEYS * 就全看见了。
登录、锁定与集市回退
登录接受邮箱或用户名。顺序是:先查锁定状态,未过锁定期直接 429;再做本地 bcrypt 校验;本地失败且标识是邮箱、又开启了集市通道时,回退到集市(SSE)校验。集市凭证一定是邮箱,所以用户名登录不走回退。
1 | // backend/src/app/handlers_auth.cpp |
锁定键同时包含邮箱和 IP。只按邮箱锁,攻击者可拿别人的邮箱把对方锁死;只按 IP 锁,换 IP 就绕过。通过后建会话、种父域 Cookie,这样各子域共享登录态。
next 参数必须经 safeNextUrl 校验成站内相对路径,否则登录页就是开放重定向跳板。重发验证同样受限流约束。
找回密码分两段:/api/auth/password-reset/start 只发码,/api/auth/password-reset/confirm 校验后改密并清掉该用户现有会话。start 对所有邮箱必须返回同样的响应,否则它就成了账号枚举接口。登出 authLogout 删会话清 Cookie,authMe 返回当前用户,authSession 返回会话摘要;GET /api/csrf-token 下发一次性令牌供写操作双提交校验。
扫码登录
PC 登录页出二维码,手机扫码确认后 PC 自动登录。后端一组接口:/api/auth/qr/start 生成带 TTL 的记录,/poll 轮询状态,/scan、/detail 给手机端看设备信息,/confirm、/deny 做决策。二维码 ID 有格式校验(validQrId),防止被当成任意 Redis 键读写。
1 | // backend/src/app/handlers_qrlogin.cpp |
确认接口要求手机端已登录,限流按「用户」而不是按二维码:同一用户 60 秒内决策超过 20 次就 429。只按二维码限流,一张码被反复确认/拒绝,状态机会被打乱。状态码也有分工:不存在走 404,过期走 410,已被他人处理走 409,前端据此给不同引导文案。集市侧还有一套 /api/auth/sse/qr/* 和 /api/auth/sse/oauth/callback,走集市二维码,回调后取集市身份做关联。
会话与设备
会话全部在 Redis(session:*)。设置页列设备由 sessionsList 扫描匹配键,解析出用户 ID,只保留当前用户的条目,按活跃时间排序,并标出哪个是当前设备。
1 | // backend/src/app/handlers_sessions.cpp |
scan("session:*", 500) 有 500 条上限。单用户会话数远小于这个值,但全站会话多时扫描成本不低,所以它只能用于用户自助查看,不能当统计口径。
「退出指定设备」按会话 ID 删;「退出其他所有」遍历该用户会话,必须显式跳过当前会话,否则用户点一下会把自己也踢下线。还有一个常被忽略的点:吊销只删服务端记录,已经签发的令牌可能仍然有效到过期;如果要求「立即失效」,令牌校验就得每次回查会话,或者维护吊销名单。资料和头像走 PUT /api/me/profile 与 GET/POST /api/me/avatar,由 user-avatar 服务做裁剪和缓存。
OAuth2 与 OIDC
第三方应用跳转过来,先由 GET /api/oauth/authorize/context 按 client_id 返回应用信息和 scope,渲染同意页。用户点同意后,服务端校验 redirect_uri 白名单(精确匹配)、校验 PKCE 参数形态、生成随机 code 存 Redis(带 TTL,authCodeSeconds),再 302 回跳并附上 state。
redirect_uri 必须精确匹配注册值。做前缀匹配,等于允许攻击者把 code 引到自己域名下的任意路径。code 只能消费一次,consumeCode 要在读取后立即删除;先读后删在并发下会被兑换两次。
1 | // backend/src/app/handlers_oauth.cpp |
PKCE 比对用常数时间比较。challenge 本身不是秘密,但统一成常数时间比较是安全惯例,成本几乎为零。校验通过后签发 access / refresh / id_token。
/api/oauth/userinfo 按 Bearer token 返回 claim;/api/oauth/introspect 供资源服务器校验令牌,调用方要先通过 client 身份认证。
1 | void oauthIntrospect(const Request& req, Response& res) { |
introspect 的默认值必须是 active=false。默认 true 再逐项排查,任何分支遗漏都会变成「伪令牌通过校验」。
发现文档在 /.well-known/openid-configuration,公钥在 /.well-known/jwks.json(RsJwt::jwks()),带 Cache-Control: public, max-age=300,缓存 5 分钟。令牌体系分两套:内部会话 JWT 用 HMAC,单一密钥、单服务校验;对外 OIDC id_token 用 RSA,多方验签、公钥公开。用途不同,密钥体系也不同。
机器对机器接口有 password/verify、session/verify、session/revoke、users/list、developer/update,统一由 m2mAuthorized 鉴权,凭证走 Basic 或表单。developerWrite 参数区分读写:同一个 client 凭证不该同时具备「查用户」和「改开发者信息」的能力。
应用与授权管理
第三方提交应用申请(名称、回调地址、scope),管理员审核通过后发放 client_id / secret;内部应用由管理员直接建。接口是 /api/apps/apply、/api/apps/pending、/api/apps/{id}/review。重置 secret(/api/apps/{id}/reset-secret)之后,旧 secret 必须立即失效,并清理该应用现有令牌——只换 secret 不吊销令牌,等于给旧凭证留了一个继续使用的窗口。
「我的授权」由 consents 表支撑,按「用户 + 应用」记一条,撤销后该应用下次访问要重新同意。外部身份只有列表和解绑接口(/api/identities、/api/identities/{id}),绑定入口被刻意关闭:身份只能通过一次校验过的集市 OAuth 回环建立。开放「直接 POST 绑定」等于允许把任意邮箱绑到自己账号,就是账号接管;绑定必须能证明「你确实拥有那个身份」。首页应用展示是公开列表加管理员 CRUD 和图标上传。
后台与可观测
管理员可以增删改查用户,但删除走停用,物理删除会打断外键引用。前端日志打到 /api/logs/client,管理员可列日志文件、查看末尾若干行(/api/admin/logs、/api/admin/logs/{file})。后者的文件名必须做白名单或路径归一化;直接拼路径,..%2F 就能读任意文件。
存储故障有统一降级:所有依赖存储的 handler 包一层 storageAware,捕获 StorageUnavailable 后统一返回 503 并给 Retry-After。
1 | // backend/src/app/routes.cpp |
把「存储故障」建模成一种异常类型、在路由层统一转 503,比每个 handler 各写一套 try-catch 可靠——新增接口不会漏掉。
面试速答
- 注册:验证码 HMAC 后存 Redis,按邮箱摘要和 IP 双限流,待验证态与正式用户分离;比对用常数时间,Redis 键不出现明文邮箱。
- 登录:本地 bcrypt 优先,失败且标识为邮箱时回退集市校验;锁定键是邮箱加 IP,
next只允许站内相对路径。 - 扫码:二维码记录带 TTL,确认按用户限流,过期 410、已被处理 409、参数错误 400。
- OAuth2:
redirect_uri精确匹配、code 一次性、PKCE 常数时间比对、introspect 默认active=false;内部会话用 HMAC JWT,对外 id_token 用 RSA + JWKS(缓存 300 秒)。 - 会话:Redis
session:*,可看设备、踢单台、踢其他所有;吊销只删服务端记录,要即时失效必须回查会话或维护吊销名单。 - 边界:UniSSO 只管身份;应用内角色、用户组、资源权限归各应用自己。
→ 下一篇:图床:上传、鉴权与存储





