本页目录展开
  1. 注册与验证码
  2. 登录、锁定与集市回退
  3. 扫码登录
  4. 会话与设备
  5. OAuth2 与 OIDC
  6. 应用与授权管理
  7. 后台与可观测
  8. 面试速答

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// backend/src/app/registration.cpp
std::string pendingKey(const std::string& email) {
return "registration_pending:" + digestEmail(email);
}
std::string codeHash(const std::string& code) {
auto& cfg = AppConfig::get();
std::string key = cfg.secretKey.empty() ? cfg.signingKeyId : cfg.secretKey;
return util::hex(util::hmacSha256Raw(key, code));
}
std::string randomCode() {
static std::atomic<unsigned int> counter{0};
std::random_device rd;
unsigned int value = rd() + counter.fetch_add(1);
return std::to_string(100000 + (value % 900000)); // 固定 6 位
}
bool rateLimited(const std::string& email, const std::string& ip) {
long long emailCount = Cache::incr("registration_email_hour:" + digestEmail(email), 3600);
...
}

两个坑。第一,验证码比对要「哈希后常数时间比较」:直接比明文,Redis 泄露等于验证码泄露;用普通 == 比较,理论上有时序侧信道。第二,限流键用邮箱摘要:写原文会把全站邮箱暴露在 Redis 键名里,运维一条 KEYS * 就全看见了。

登录、锁定与集市回退

登录接受邮箱或用户名。顺序是:先查锁定状态,未过锁定期直接 429;再做本地 bcrypt 校验;本地失败且标识是邮箱、又开启了集市通道时,回退到集市(SSE)校验。集市凭证一定是邮箱,所以用户名登录不走回退。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// backend/src/app/handlers_auth.cpp
void authLogin(const Request& req, Response& res) {
std::string identifier = util::trim(http::input(req, "email"));
std::string email = util::lower(identifier);
std::string password = http::input(req, "password");
std::string next = safeNextUrl(http::input(req, "next"));
std::string ip = http::clientIp(req);
long long lockedUntil = 0;
if (isLocked(email, ip, lockedUntil)) {
http::error(res, 429, "too_many_attempts", "登录尝试次数过多,请 15 分钟后再试");
return;
}
auto user = identifier.find('@') == std::string::npos
? repo::findUserByUsername(identifier)
: repo::findUserByEmail(email);
bool authenticated = user && user->isActive && password::verify(password, user->passwordHash);
// 本地失败时,若开启集市通道且标识是邮箱,回退到集市校验
if (!authenticated && AppConfig::get().sseEnabled && email.find('@') != std::string::npos) { ... }
}

锁定键同时包含邮箱和 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// backend/src/app/handlers_qrlogin.cpp
void qrLoginConfirm(const Request& req, Response& res) {
User user;
if (!authx::requireUser(req, res, user)) return;
std::string id = util::trim(http::input(req, "id"));
if (!validQrId(id)) { http::error(res, 400, "invalid_id", "二维码参数不正确"); return; }
long long decides = Cache::incr("qr_login_decide:" + user.id, 60);
if (decides > 20) { http::error(res, 429, "rate_limited", "操作过于频繁,请稍后再试"); return; }
std::map<std::string, JsonValue> rec;
if (!loadRecord(id, rec)) { http::error(res, 410, "qr_expired", "二维码已过期,请回到电脑上刷新"); return; }
std::string status = statusOf(rec);
if (status == "confirmed") {
if (jsonx::getString(rec, "user_id") == user.id) { http::ok(res); return; }
http::error(res, 409, "already_handled", "这个二维码已在其他设备上处理");
return;
}
if (status == "denied") { http::error(res, 409, "already_denied", "这个二维码已被拒绝"); return; }
...
}

确认接口要求手机端已登录,限流按「用户」而不是按二维码:同一用户 60 秒内决策超过 20 次就 429。只按二维码限流,一张码被反复确认/拒绝,状态机会被打乱。状态码也有分工:不存在走 404,过期走 410,已被他人处理走 409,前端据此给不同引导文案。集市侧还有一套 /api/auth/sse/qr/* 和 /api/auth/sse/oauth/callback,走集市二维码,回调后取集市身份做关联。

会话与设备

会话全部在 Redis(session:*)。设置页列设备由 sessionsList 扫描匹配键,解析出用户 ID,只保留当前用户的条目,按活跃时间排序,并标出哪个是当前设备。

1
2
3
4
5
6
7
8
9
// backend/src/app/handlers_sessions.cpp
for (const auto& name : Cache::scan("session:*", 500)) {
std::string raw = Cache::get(name);
if (raw.empty()) continue;
SessionInfo info;
if (!parseSession(name, raw, info) || info.userId != user.id) continue;
info.current = currentId && info.id == *currentId;
sessions.push_back(info);
}

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
2
3
4
5
6
7
8
9
10
11
12
13
14
// backend/src/app/handlers_oauth.cpp
bool verifyPkce(const std::string& verifier, const std::string& challenge) {
if (verifier.empty()) return false;
return util::constantTimeEquals(util::base64UrlEncode(util::sha256Raw(verifier)), challenge);
}
// grant_type=authorization_code 的校验顺序
auto data = consumeCode(code);
if (!data) { oauthError(res, 400, "invalid_grant", "authorization code invalid or expired"); return; }
if (clientId != codeClient) { oauthError(res, 400, "invalid_grant", "client mismatch"); return; }
auto app = repo::findApplicationByClientId(codeClient);
if (!verifyClient(*app, clientSecret, clientError)) { oauthError(res, 401, "invalid_client"); return; }
if (!redirectUri.empty() && redirectUri != codeRedirect) {
oauthError(res, 400, "invalid_grant", "redirect_uri mismatch"); return;
}

PKCE 比对用常数时间比较。challenge 本身不是秘密,但统一成常数时间比较是安全惯例,成本几乎为零。校验通过后签发 access / refresh / id_token。

/api/oauth/userinfo 按 Bearer token 返回 claim;/api/oauth/introspect 供资源服务器校验令牌,调用方要先通过 client 身份认证。

1
2
3
4
5
6
void oauthIntrospect(const Request& req, Response& res) {
// 先认证调用方 client
std::map<std::string, JsonValue> obj;
obj["active"] = JsonValue(false); // 默认无效,只有校验通过才置 true
if (token.empty()) { http::json(res, 200, JsonValue(obj)); ... }
}

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
2
3
4
5
6
7
8
9
10
11
// backend/src/app/routes.cpp
auto storageAware(void (*handler)(const Request&, Response&)) {
return [handler](const Request& req, Response& res) {
try {
handler(req, res);
} catch (const StorageUnavailable&) {
http::error(res, 503, "temporarily_unavailable", "身份服务暂时不可用,请稍后重试");
res.headers["Retry-After"] = "3";
}
};
}

把「存储故障」建模成一种异常类型、在路由层统一转 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 只管身份;应用内角色、用户组、资源权限归各应用自己。

→ 下一篇:图床:上传、鉴权与存储