w wyl123ly 的博客
MD

后端-06-认证与授权

74 KB 2026.10.11 原文件

后端-06-认证与授权

这篇笔记讲什么

认证(Authentication)解决「你是谁」,授权(Authorization)解决「你能做什么」。本文覆盖:密码存储的现代做法、Cookie 会话的安全属性、JWT 的结构与四类攻击、OAuth 2.0 与 OpenID Connect 的正确用法、RBAC/ABAC/ReBAC 三种授权模型、水平与垂直越权的防御、TOTP 多因素认证,最后给出一个 JWT 认证 + 刷新令牌轮换 + RBAC 授权的完整后端实现和常见漏洞对照表。

是什么

两个词经常被混着用,但它们在代码里的落点完全不同:

维度认证(Authentication)授权(Authorization)
回答的问题你是谁?凭证是否有效?你能对这个资源做这个操作吗?
输入用户名密码 / Cookie / Token / 证书已认证的身份 + 角色/属性 + 目标资源
失败状态码401 Unauthorized403 Forbidden
必须带 WWW-Authenticate 头是(RFC 9110 要求 401 带质询)否
在 ASP.NET Core 中的落点AddAuthentication + UseAuthentication + [Authorize] 触发之前的 SignInAsyncAddAuthorization + UseAuthorization + 策略/角色/RequireAuthorization()
中间件顺序在 UseAuthorization 之前紧接认证之后
数据来源凭证存储、令牌签名、会话存储策略、角色表、资源归属关系

一句话记忆

认证失败 = 「我没认出你」;授权失败 = 「我认出你了,但你不能碰这个」。

把 403 写成 401,会让客户端去重新登录(无效),把 401 写成 403,会让已登录用户看不到「请登录」的引导。

为什么这样设计

  • 为什么密码不能明文或简单哈希存储? 数据库一定会以某种方式泄露(注入、备份外流、内部人员)。明文等于直接把密码交出去——而用户在别处复用同一密码,泄露会连环扩散。MD5/SHA-1 这类快速哈希也不行:GPU 每秒能算上百亿次,常见密码瞬间被反查。
  • 为什么要加盐(salt)? 没有盐,攻击者可以预计算彩虹表(rainbow table),一次计算命中全库;也可以看出「哪两个用户密码相同」。每个用户一个唯一随机盐,把破解成本从「一次计算」变成「逐个用户计算」。
  • 为什么要慢哈希? 正常登录时验证一次密码花 100 ms 完全可以接受,但攻击者要试十亿次就变成 3 年。故意变慢是密码哈希与普通哈希的根本区别。
  • 为什么要用无状态令牌(JWT)? 多实例部署时,有状态 Session 需要共享存储(Redis)或粘性会话(sticky session)。JWT 把身份信息装进自包含字符串,验证只需公钥,不用查库——代价是难以主动失效,这是后文大量篇幅的主题。
  • 为什么要 OAuth 2.0? 让第三方应用访问你的资源,传统做法是把密码给它(RFC 6749 明确列出了这样做的问题:第三方必须存明文密码、拿到过宽权限、用户无法单独撤销)。OAuth 引入授权层,把「客户端」和「资源所有者」两个角色分开,客户端拿到的是有范围、有期限、可单独撤销的访问令牌。
  • 为什么授权模型要分 RBAC/ABAC/ReBAC? 角色模型简单但表达力弱(「只有文档所有者能编辑」表达不了);属性模型表达力强但难审计;关系模型适合社交/协作类大规模图。选错模型会导致权限表爆炸或性能崩塌。

核心内容

一、密码存储

算法对比与参数选择
算法抗 GPU抗内存并行参数OWASP 推荐最低配置备注
Argon2id强强内存 m / 迭代 t / 并行 pm=19456(19 MiB), t=2, p=1首选;2015 年密码哈希竞赛冠军,id 变体兼顾侧信道与 GPU 抗性
scrypt强强N / r / pN=2^17(128 MiB), r=8, p=1Argon2id 不可用时使用
bcrypt中弱工作因子 costcost ≥ 10,密码长度上限 72 字节仅用于遗留系统;有 72 字节截断与 null 字节两个坑
PBKDF2弱弱迭代次数 + 内部哈希HMAC-SHA256 ≥ 600,000 次需要 FIPS-140 合规时的选择
MD5 / SHA-1 / SHA-256(裸用)无无—禁止速度太快,等于没保护

Argon2id 的另外几组等效配置(防护理度相同,只在 CPU 与内存之间取舍):m=47104/t=1、m=12288/t=3、m=9216/t=4、m=7168/t=5,p 均为 1。

bcrypt 的两个坑

1. 72 字节截断:多数实现对超过 72 字节的部分直接忽略,且遇到 null 字节就停止。若先做 bcrypt(sha256(password)) 这种「预哈希」,哈希结果里的 null 字节会让截断行为变得难以推理,还可能引入 password shucking 攻击。真要预哈希,应写成 bcrypt(base64(hmac-sha384(password, pepper))) 并把 pepper 存到数据库之外。

2. 不要把 pepper 存在数据库里:pepper 是全局共享的密钥,必须放在密钥管理服务或 HSM 中。它泄露后无法直接更换(换 pepper 会作废所有密码哈希,必须强制全员改密)。

工作因子要随硬件提升

工作因子(work factor)是「每次验证故意花多少计算」。硬件每年变强,所以工作因子的正确做法是可升级、且能渐进迁移:

  1. 把算法标识与参数写进哈希字符串本身(PHC 标准格式,如 $argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>),这样新旧哈希可以共存。
  2. 硬件升级后调高参数,新注册用户用新参数。
  3. 老用户在下次登录成功时(此刻明文密码在手)用新参数重新哈希并覆盖。
  4. 长期不登录的账号可考虑直接清空密码哈希、强制重置,避免老弱哈希长期留在库里。

调参的判据

目标是「单次哈希耗时接近但不超过 ~1 秒」,同时不能高到让攻击者能用大量登录请求打满 CPU 造成拒绝服务。参数必须在目标服务器上实测,不要照抄别人博客的数字。

.NET 实现(PBKDF2-HMAC-SHA256)
using System.Security.Cryptography;

public static class PasswordHasher
{
    // 参数写进字符串,便于将来升级而不破坏旧哈希
    private const int SaltSize = 16;          // 128 位盐
    private const int KeySize = 32;           // 256 位派生密钥
    private const int Iterations = 600_000;   // OWASP 对 PBKDF2-HMAC-SHA256 的建议下限
    private const char Delimiter = '$';
    private const string Algorithm = "pbkdf2-sha256";

    public static string Hash(string password)
    {
        // 盐必须是密码学安全的随机数,Random 不行
        var salt = RandomNumberGenerator.GetBytes(SaltSize);
        var key = Rfc2898DeriveBytes.Pbkdf2(
            password: password,
            salt: salt,
            iterations: Iterations,
            hashAlgorithm: HashAlgorithmName.SHA256,
            outputLength: KeySize);

        return string.Join(Delimiter, Algorithm, Iterations, Convert.ToBase64String(salt), Convert.ToBase64String(key));
    }

    public static bool Verify(string password, string stored)
    {
        var parts = stored.Split(Delimiter);
        if (parts.Length != 4 || parts[0] != Algorithm) return false;
        if (!int.TryParse(parts[1], out var iterations)) return false;

        byte[] salt, expected;
        try
        {
            salt = Convert.FromBase64String(parts[2]);
            expected = Convert.FromBase64String(parts[3]);
        }
        catch (FormatException) { return false; }

        var actual = Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, HashAlgorithmName.SHA256, expected.Length);

        // 必须用固定时间比较:普通 == 会短路返回,攻击者可据响应时间逐字节猜出哈希
        return CryptographicOperations.FixedTimeEquals(actual, expected);
    }

    // 登录成功后判断是否需要按当前参数重新哈希(工作因子升级)
    public static bool NeedsRehash(string stored)
    {
        var parts = stored.Split(Delimiter);
        return parts.Length != 4 || parts[0] != Algorithm
            || !int.TryParse(parts[1], out var it) || it < Iterations;
    }
}

Python 侧(passlib 已长期缺少维护,新项目建议直接用 argon2-cffi;若仍用 passlib,注意其 bcrypt 后端与新版库的兼容告警):

# pip install argon2-cffi
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError

# 参数与 OWASP 推荐一致;hash() 会自动生成随机盐并把参数编码进结果字符串
ph = PasswordHasher(time_cost=2, memory_cost=19456, parallelism=1, hash_len=32, salt_len=16)

def hash_password(pw: str) -> str:
    return ph.hash(pw)                      # 形如 $argon2id$v=19$m=19456,t=2,p=1$...

def verify_password(pw: str, stored: str) -> tuple[bool, bool]:
    try:
        ph.verify(stored, pw)
        return True, ph.check_needs_rehash(stored)   # (是否通过, 是否需要升级参数)
    except VerifyMismatchError:
        return False, False
迁移旧哈希(MD5/SHA-1)
策略做法代价
登录时透明升级用户下次登录、明文密码在手时用新算法重新哈希并覆盖长期不登录的账号仍是弱哈希
套娃哈希直接把 md5(pw) 当输入:argon2id(md5(pw))无需明文即可全量迁移,但弱哈希仍在,且削弱了安全性
强制重置清空哈希,要求全员通过邮件/短信重置密码最安全,但用户体感差、客服压力大

推荐组合

先用「套娃」在不停机的情况下把全库算法标识统一到强算法,再配合「登录时透明升级」逐步把弱哈希替换掉,最后对长期不活跃账号执行强制重置。

有状态方案的本质:服务端保存会话数据,客户端只拿一个不可猜的会话 ID。

登录成功 → 服务端生成随机会话 ID(≥128 位)→ 存入会话存储(Redis/DB)
        → Set-Cookie: SESSIONID=xxx; HttpOnly; Secure; SameSite=Lax; Path=/
后续请求 → 浏览器自动带上 Cookie → 服务端用 ID 查出会话 → 得到用户身份
登出    → 服务端删除该会话 → 即使 Cookie 还在也无效
Cookie 属性作用注意
HttpOnly禁止 JavaScript 通过 document.cookie 读取防 XSS 窃取会话的第一道闸;认证 Cookie 必须加
Secure只在 HTTPS 上发送防止明文网络中被嗅探;生产必须加
SameSite=Strict任何跨站请求都不带上最安全,但从外部站点跳转进来会「掉登录态」
SameSite=Lax仅顶级导航的 GET 带上默认值,兼容性与安全性平衡较好
SameSite=None总是带上必须同时加 Secure;用于真正需要跨站嵌入的场景(如第三方支付回调)
Domain指定哪些域能收到省略则仅当前域(不含子域)。不要设成 .example.com,那会让所有子域(含被他人接管的测试子域)都能读到会话
Path限定路径范围不能作为安全边界:同源下别的路径可以用别的方式读取。只能减少无谓传输
Max-Age / Expires持久化与过期省略则是会话 Cookie,浏览器关闭即失效(但单个标签页关闭不清除)

ASP.NET Core 10 的行为变化

从 ASP.NET Core 10 开始,启用 Cookie 认证时,已知的 API 终结点不再重定向到登录页,而是直接返回 401/403。这对前后端分离项目是好事(前端不必再解析 302 跳转),但对既有系统是行为变更,升级时需要回归。以官方最新文档为准。

会话固定攻击与登录后换 ID

会话固定攻击(Session Fixation):攻击者先访问站点拿到一个会话 ID,再设法让受害者用这个 ID 登录(例如通过 URL 参数注入、XSS 写 Cookie、或诱导访问带 ?sessionid= 的链接)。受害者登录后,服务端把该 ID 标记为「已认证」,攻击者手里的同一个 ID 就变成了合法凭证。

防御:登录成功后必须作废旧会话 ID 并签发新的。

// 登录成功后:先清掉当前会话(含旧 Cookie),再写入新身份
await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

var claims = new List<Claim>
{
    new(ClaimTypes.NameIdentifier, user.Id.ToString()),
    new(ClaimTypes.Name, user.UserName),
    new(ClaimTypes.Role, "User"),
    new("session_version", user.SessionVersion.ToString())   // 用于全局踢下线
};
var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);

await HttpContext.SignInAsync(
    CookieAuthenticationDefaults.AuthenticationScheme,
    new ClaimsPrincipal(identity),
    new AuthenticationProperties
    {
        IsPersistent = false,                       // 「记住我」才设 true,且要用户显式勾选
        ExpiresUtc = DateTimeOffset.UtcNow.AddHours(8)
    });
分布式场景:粘性问题
方案做法问题
粘性会话(sticky session)负载均衡把同一用户固定到同一实例,会话存本机内存实例重启/扩缩容即掉线;负载不均;无法优雅发布
集中式会话存储会话放 Redis/数据库,所有实例共享需要额外组件与网络往返,但是正确做法
数据保护密钥共享ASP.NET Core 的 Cookie 是加密的,多实例必须共享 Data Protection 密钥环不共享会导致「换个实例就登录失效」
// 多实例部署:把数据保护密钥持久化到共享位置,并用应用名做隔离
builder.Services.AddDataProtection()
    .PersistKeysToStackExchangeRedis(redis, "DataProtection-Keys")
    .SetApplicationName("DemoApi");

三、JWT

结构:三段式

一个签名 JWT(JWS)是 base64url(header).base64url(payload).base64url(signature):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 . eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0 . KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30
└──────── 头部 header ────────┘   └──────────────────── 载荷 payload ────────────────────┘   └──────────── 签名 signature ────────────┘

解码后:

// header
{ "alg": "HS256", "typ": "JWT" }

// payload(claims)
{ "sub": "1234567890", "name": "John Doe", "admin": true, "iat": 1516239022 }

签名计算:

注意 payload 只是 base64url,不是加密——任何人都能解开看内容。

常用声明(claims)
声明全称含义安全影响
ississuer签发者不校验会让任意签发者的令牌被接受
subsubject主体(用户标识)跨签发者必须配合 iss 一起看,否则可跨系统冒充
audaudience预期接收方不校验会让给 A 服务签的令牌能用来打 B 服务
expexpiration time过期时间(Unix 秒)必须校验
nbfnot before生效时间必须校验
iatissued at签发时间可用于拒绝「签发于密码修改之前」的令牌
jtiJWT ID令牌唯一标识黑名单与审计的基础
scope—OAuth 2 授权范围权限过度授予的根源
roles / groups—角色/组跨签发者伪造角色是常见越权路径
amr / acrauth method / class认证方式与强度用于强制「敏感操作必须走 MFA」
签名 vs 加密:JWS vs JWE
JWS(签名)JWE(加密)
目的完整性 + 真实性:内容不可篡改、来源可信机密性:内容不可读
结构三段(header.payload.signature)五段(header.encrypted_key.iv.ciphertext.tag)
内容可见是(base64url,任何人可解码)否
典型 alg / encRS256 / ES256 / HS256RSA-OAEP / A256GCM
适用Access Token、ID Token(本来就要给客户端读)需要承载敏感个人信息时

签名 ≠ 保密

把手机号、身份证号直接塞进 JWS payload 是信息泄露——任何拿到令牌的人(包括浏览器端脚本、日志系统、代理)都能解开。要么不放敏感数据,要么改用 JWE。

攻击一:alg: none

早期的 JWT 库在头部 alg 为 none 时会跳过签名校验。攻击者只需把 header 改成 {"alg":"none"}、伪造 payload、去掉签名段,就能冒充任意用户。现代库默认已拒绝 none,但仍需确认你用的库版本与配置。

攻击二:算法混淆(Algorithm / Key Confusion)

服务端原本用 RS256(非对称,公钥验证)。攻击者把 alg 改成 HS256(对称,共享密钥验证),然后用公开可得的 RSA 公钥当作 HMAC 密钥来签名。若库根据 header 里的 alg 动态选算法、又把公钥当对称密钥用,就会验证通过。

防御:验证时把允许的算法硬编码为白名单,且绝不混用非对称与对称算法。

// .NET 的 JwtBearer 默认只信任配置中显式给出的算法,不会跟随 header 里的 alg
options.TokenValidationParameters = new TokenValidationParameters
{
    ValidateIssuer = true,
    ValidIssuer = jwt.Issuer,
    ValidateAudience = true,
    ValidAudience = jwt.Audience,
    ValidateIssuerSigningKey = true,
    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwt.Secret)),
    ValidateLifetime = true,
    ClockSkew = TimeSpan.FromSeconds(30),      // 见下文「时钟偏移」
    ValidAlgorithms = [SecurityAlgorithms.HmacSha256],   // 显式白名单,杜绝算法混淆
    NameClaimType = ClaimTypes.NameIdentifier
};
攻击三:信任令牌自带的密钥指针

header 里的 jwk(内嵌公钥)、jku(JWK Set 的 URL)、x5u / x5c(证书)都未经签名保护,属于攻击者可控输入。若验证方从这些字段取密钥,攻击者带上自己的公钥并用对应私钥签名,就能伪造令牌。kid 也可能被用作注入向量(它常被拼进数据库查询或文件路径)。

防御:验证密钥必须来自带外信任的固定来源(配置里的密钥、签发者元数据里的 jwks_uri)。kid 只能用于在已配置的密钥集合内选择,不能作为信任来源。

攻击四:签发者 / 接收方混淆

同一套密钥用于多个环境或多个服务时,测试环境签发的令牌可能被生产接受。防御:每个环境独立密钥;严格校验 iss + aud;typ 头部用于区分令牌类型,避免拿 ID Token 当 Access Token 用(ID Token 绝不应用于访问 API)。

为什么 JWT 难以主动失效

JWT 的验证是「验签 + 看时间」,服务端不查库。所以下列操作不会让已签发的 JWT 立即失效:改密码、退出登录、管理员封禁账号、权限变更。

两种缓解方案:

方案机制优点缺点
短过期 + 刷新令牌Access Token 5–15 分钟,过期用 Refresh Token 换新的无需服务端状态,失效延迟有上界延迟窗口内令牌仍有效;刷新接口成为高价值目标
黑名单 / 拒绝列表(denylist)维护已撤销 jti 集合,每次请求查一次可以做到即时失效引入服务端状态(Redis 查询),JWT「无状态」的核心优势被抵消

工程上的折中

Access Token 设短(5–15 分钟)+ Refresh Token 存服务端可撤销。真正需要「立刻踢下线」的操作(改密码、封号、异地登录告警)通过提升 session_version 实现:把版本号写进 Access Token,验证时比对;不一致就拒绝。这样只多一次轻量缓存查询,却获得了接近即时的失效能力。

刷新令牌的轮换与重放检测

刷新令牌轮换(Refresh Token Rotation):每次用 Refresh Token 换新 Access Token 时,同时签发新的 Refresh Token 并作废旧的。

重放检测:如果某个已被使用过的 Refresh Token 又被拿来使用,说明它被窃取了(合法客户端已经在用新的那个)。此时应当撤销整个令牌家族,强制该用户重新登录。

正常流程:
  RT₀ → 换到 (AT₁, RT₁),RT₀ 作废
  RT₁ → 换到 (AT₂, RT₂),RT₁ 作废

被盗场景:
  攻击者偷到 RT₁ 并用掉 → 服务端签发 (AT₂, RT₂),RT₁ 标记为已用
  合法客户端也拿着 RT₁ 来用 → 服务端发现 RT₁ 已被用过
  ⇒ 判定泄露,撤销该用户全部 Refresh Token,要求重新登录

RFC 9700 的强制要求

公共客户端(无法安全保存密钥的客户端,如 SPA、移动端)的 Refresh Token 必须做发送方约束(sender-constrained,如 DPoP/MTLS)或使用轮换。同一份 BCP 还明确:资源所有者密码凭证授予(password 授权类型)不得使用,隐式流程(response_type=token)应停止使用。

时钟偏移与 exp / nbf / iat

exp、nbf、iat 都是 Unix 秒。多台服务器时钟不可能完全一致,因此验证时通常允许一个小的容差(clock skew),.NET 默认是 5 分钟——这个默认值偏大,建议压到 30 秒左右。

// 默认 5 分钟容差对短生命周期的 Access Token 太宽松:
// 一个 10 分钟有效的令牌实际能多用 5 分钟
options.TokenValidationParameters.ClockSkew = TimeSpan.FromSeconds(30);

生产环境必须配置 NTP 时间同步,否则偏移超过容差会导致大面积「令牌莫名失效」。

密钥管理与轮换
算法族密钥轮换要点
HS256(HMAC)签发方与验证方共享同一密钥密钥长度至少等于输出长度(HS256 ≥ 256 位),熵 ≥ 160 位;不同接收方/签发者必须用不同密钥,否则一方可伪造另一方
RS256 / PS256 / ES256私钥签名、公钥验证公钥可公开分发(jwks_uri),轮换简单:JWKS 里同时发布新旧公钥,用 kid 区分,等旧令牌全部过期后再移除旧公钥
// 轮换期:JWKS 中保留新旧两把公钥,新令牌用新 kid
// 验证方按 header.kid 在「已配置的密钥集合」中查找 → 平滑过渡,无需停机

禁止做的事

不要用密码、项目名、随机短字符串当 HMAC 密钥。OWASP 给出的合法示例是 secrets.token_bytes(256//8) 这种密码学安全随机源生成的 32 字节。也不要把同一密钥同时用于签名和加密。

令牌该存哪里
存储位置XSS 风险CSRF 风险能否被 JS 读取结论
localStorage / sessionStorage高:任意 XSS 都能读走全部令牌无(不会自动携带)是不推荐存长期凭证
内存(JS 变量)中:XSS 仍可读,但刷新即丢失无是仅适合短命 Access Token
HttpOnly + Secure + SameSite Cookie低:JS 读不到有:浏览器会自动携带否推荐,但必须配套 CSRF 防御
Cookie + CSRF Token(双提交 / 同步器令牌)低低否前后端分离的推荐组合
BFF 模式(Backend for Frontend)最低:令牌只存在服务端,浏览器只有会话 Cookie有(用 SameSite + CSRF Token 解决)否安全要求高时的首选

结论

不要把 Access Token / Refresh Token 放进 localStorage。 一次 XSS 就等于账号完全失守,且攻击者可以用 Refresh Token 长期续命。

推荐:HttpOnly; Secure; SameSite=Lax(或 Strict)的 Cookie 承载会话,配合 CSRF Token;或者干脆用 BFF 模式,让浏览器完全接触不到令牌。注意,SameSite=Lax 仍允许顶级导航的 GET 带 Cookie,因此所有写操作必须用 POST/PUT/DELETE 并校验 CSRF Token。

四、OAuth 2.0 与 OpenID Connect

要解决的授权委托问题

RFC 6749 列出了「把密码交给第三方」的四个根本问题:第三方必须存明文密码以备后用;服务端不得不支持密码认证(尽管密码本身很弱);第三方获得过宽的权限,用户无法限制范围与时长;用户无法单独撤销某一个第三方的访问(只能改密码,连带撤销所有第三方)。

OAuth 引入授权层,把客户端(client)和资源所有者(resource owner)分开:客户端拿到的是有范围(scope)、有生命周期、可单独撤销的访问令牌。

四种角色
角色英文说明
资源所有者resource owner能授予受保护资源访问权的实体;通常就是用户
客户端client代表资源所有者发起受保护资源请求的应用
授权服务器authorization server在成功认证资源所有者并取得授权后,向客户端签发访问令牌
资源服务器resource server托管受保护资源,能接受并响应携带访问令牌的请求
四种授权类型
授权类型交互形态适用场景现状
授权码(authorization code)浏览器重定向拿 code,后端用 code 换令牌服务端 Web 应用、SPA、移动/桌面应用推荐,配合 PKCE
隐式(implicit)令牌直接从重定向 URL 片段返回曾用于纯前端 SPA已废弃:令牌暴露在 URL(历史记录、Referer、日志),且无法使用发送方约束
密码凭证(resource owner password credentials)客户端直接收用户名密码曾用于自家移动端不得使用(RFC 9700 明确禁止):客户端能拿到密码,攻击面扩大,且不兼容 MFA
客户端凭证(client credentials)客户端用自身凭据换令牌无用户参与的服务间调用推荐用于机器对机器
为什么现在推荐「授权码 + PKCE」

PKCE(Proof Key for Code Exchange,RFC 7636)解决的是授权码被拦截的问题:

1. 客户端生成随机 code_verifier(43~128 字符)
2. 计算 code_challenge = BASE64URL(SHA256(code_verifier)),method = S256
3. 授权请求带上 code_challenge + code_challenge_method=S256
4. 授权服务器回调返回 code
5. 客户端用 code + code_verifier 换令牌
6. 授权服务器校验 SHA256(code_verifier) == 之前存的 code_challenge

即使攻击者截获了 code(例如通过不严格的重定向 URI 校验、或移动端应用劫持回调),没有 code_verifier 也换不到令牌。PKCE 同时还能防 CSRF 与授权码注入。

PKCE 的细节要求

- code_challenge_method 必须用 S256。plain 会把 verifier 明文放进授权请求,任何能读到授权请求(浏览器历史、代理日志)的攻击者都能绕过 PKCE 的保护。

- 每个 code_challenge 必须是单次事务专属并与发起时的用户代理绑定。

- 授权服务器必须防止 PKCE 降级攻击:只有当授权请求里带了 code_challenge 时,才接受令牌请求里的 code_verifier。

- 授权服务器必须支持 PKCE,并建议在元数据里公布 code_challenge_methods_supported。

Access Token / Refresh Token / ID Token 的区别
Access TokenRefresh TokenID Token
用途访问被保护资源换取新的 Access Token向客户端证明用户已认证,并传递身份属性
给谁看只给资源服务器;客户端不应解析只给授权服务器给客户端(它本来就是给客户端读的)
格式任意(可以是 JWT,也可以是引用令牌)任意必须是 JWT
生命周期短(分钟级)长(天/月级)与认证会话相关
能否用来访问 API是否绝对不能
是否包含用户资料通常不含不含含(sub、name、email 等)

三条铁律

1. 不要把 ID Token 发给 API。它是给客户端验证登录用的。

2. 不要在客户端(UI)里解析 Access Token。它是给资源服务器的,格式不保证是 JWT,某些实现还会加密。

3. 不要自己造访问令牌。要走 OpenID Connect 或 OAuth 标准流程;自造令牌只适合封闭的测试场景。

授权码 + PKCE 的报文流
# ① 授权请求(浏览器跳转)
GET /authorize?response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
    &scope=openid%20profile%20api.read
    &state=xyz                                    # 防 CSRF 的一次性值
    &code_challenge=YTFjNjI1OWYz...&code_challenge_method=S256
Host: server.example.com

# ② 授权响应(回调,携带 code)
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

# ③ 换取令牌(后端对后端,用户看不到)
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

# ④ 令牌响应
{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

授权码的时效与一次性

RFC 6749 建议授权码最长 10 分钟,且只能使用一次。若同一个 code 被使用两次,授权服务器必须拒绝请求,并应尽可能撤销所有基于该 code 签发的令牌。

五、授权模型

模型全称判定依据表达力适用规模典型例子
RBACRole-Based Access Control用户 → 角色 → 权限弱(难表达「仅本人」)中小系统,角色数 < 几十「管理员可删除商品」
ABACAttribute-Based Access Control主体/资源/环境属性组合成策略强中大型、规则复杂的系统「部门经理在工作时间可审批本部门 ≤ 5 万元的报销」
ReBACRelationship-Based Access Control实体之间的关系图强(天然表达共享/继承)协作类、社交类,关系规模大「文档的编辑者可评论,协作者可查看」

混合是常态

实践中常见「RBAC 打底 + 少量 ABAC 规则」:粗粒度用角色(谁能进管理后台),细粒度用属性与归属(只能改自己的订单)。ReBAC 只在关系本身构成核心业务语义时才值得引入(Google Zanzibar 类系统)。

权限检查放在哪一层
层次手段适合不适合
路由/终结点层[Authorize(Roles="Admin")]、.RequireAuthorization("policy")垂直权限(功能级准入)判断不了「这条数据是不是你的」
服务层在业务方法入口做策略检查(IAuthorizationService.AuthorizeAsync(user, resource, policy))复杂策略、跨多个资源的规则容易被新加的调用方绕过
数据层查询条件强制带归属过滤(WHERE owner_id = @me)水平权限(行级隔离)的最后防线表达不了复杂业务规则

正确做法是纵深防御:路由层挡掉未登录与角色不符的请求;服务层做资源级授权;数据层用查询条件兜底。任何一层单独承担都可能被绕过。

水平越权与垂直越权
垂直越权(Vertical)水平越权(Horizontal)
含义低权限用户执行了高权限功能同权限用户访问了别人的数据
例子普通用户调用 /api/admin/users用户 A 把 URL 里的 orderId 换成用户 B 的,读到了 B 的订单
本质权限层级校验缺失资源归属校验缺失
常见成因只在菜单/前端隐藏入口,后端没校验只信任前端传来的 ID,直接 db.Orders.Find(id)
防御每个端点显式声明所需角色/策略;默认拒绝查询条件强制带 owner_id;找不到就返回 404

最危险的写法

```csharp

// ❌ 只按主键查,完全没有归属校验 → 任何人改个 id 就能读别人的数据

var order = await db.Orders.FindAsync(id);

return order is null ? NotFound() : Ok(order);

```

绝不能信任前端传来的资源 ID 代表「用户有权访问的资源」。 ID 只说明「用户想访问哪个资源」,是否有权必须由服务端判定。

另外,越权失败时返回 404 而不是 403 更安全:403 会泄露「这个资源确实存在」,让攻击者可以枚举 ID 探测数据规模。

六、多因素认证

TOTP 原理(RFC 6238)

TOTP(Time-Based One-Time Password)是 HOTP(RFC 4226)的时间变体。核心公式:

其中 是客户端与服务端共享的密钥, 是时间步长(默认 30 秒), 是起始时间(默认 0)。

HOTP 的计算与截断:

其中 是由哈希末字节低 4 位决定的动态截断偏移, 是输出位数(通常 6)。

实现要点:

  • 时间步长默认 30 秒,这是 RFC 6238 在安全与可用性之间的平衡点。
  • 允许的网络延迟窗口最多一个时间步(即验证当前步与上一步,共 2 个候选)。窗口越大,攻击者的可利用时间越长。
  • 同一个 OTP 在成功验证后不得再次接受——否则在 30 秒窗口内被窃听的 OTP 可被重放。
  • 时钟漂移(clock drift):验证器应记录每个用户的偏移量,在后续验证时用偏移校正后的时间计算。
  • 密钥建议长度与 HMAC 输出等长(SHA-1 时 20 字节),并用密码学安全随机源生成。
其他因素
方式说明优缺点
TOTP(认证器 App)共享密钥 + 时间派生 6 位码免费、离线可用;对钓鱼不免疫(用户会把码输给假网站)
短信 OTP短信下发一次性码易受 SIM 卡交换攻击与 SS7 拦截;不建议作为唯一第二因素
恢复码(recovery codes)注册 MFA 时生成的一组一次性码必须有——否则用户丢设备就永久锁死。需哈希存储、一次性使用、可重新生成
Passkey / WebAuthn基于公私钥,私钥存在设备安全芯片中,用生物识别解锁抗钓鱼(密钥绑定源站)、无需共享密钥;是当前最强的通用第二因素/无密码方案

MFA 的正确落点

MFA 只在登录时验证是不够的。敏感操作(改密码、改绑定手机、转账、删除账号)应当用 acr / amr 声明或短时效的「最近一次 MFA 时间戳」做二次校验,防止会话被劫持后直接执行高危操作。

七、会话安全实践清单

实践具体要求
登录失败限流按账号 + IP + 设备指纹多维计数;失败次数越多延迟越长(指数退避);超过阈值锁定并通知用户
账号锁定优先用「渐进延迟」而非硬锁定,避免攻击者用错误密码故意锁死他人账号(拒绝服务)
验证码只在判定为可疑时出现(连续失败、异常 IP、异常频率)。全站必填验证码会大幅伤害转化率
密码重置令牌一次性、有效期 ≤ 15 分钟、密码学安全随机、绑定账号与用途、使用后立即作废;重置链接在密码变更后立即失效
不泄露账号是否存在登录失败统一提示「用户名或密码错误」;注册时不要直接说「该邮箱已注册」;忘记密码页面无论账号是否存在都显示「如果该邮箱已注册,我们已发送邮件」,且响应时间要接近(否则可被计时攻击区分)
会话过期同时设置空闲超时与绝对超时;敏感操作要求重新认证
登出服务端销毁会话(不只是清 Cookie);有 Refresh Token 时一并撤销整个令牌家族
并发会话管理提供「查看已登录设备」与「登出其他设备」;改密码时使所有其他会话失效
传输安全全站 HTTPS + HSTS;认证 Cookie 必须 Secure
审计日志记录登录成功/失败、权限变更、敏感操作,含时间、IP、UA、请求 ID;不要记录密码与令牌明文

八、完整实现:JWT 认证 + 刷新令牌 + RBAC

下面是一个可直接运行的最小实现。项目结构:

dotnet new web -n SecureApi && cd SecureApi
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Design
1. 配置与选项

appsettings.Development.json(生产用环境变量或密钥服务覆盖):

{
  "Jwt": {
    "Issuer": "https://localhost:5001",
    "Audience": "secure-api",
    "SigningKey": "请用 dotnet user-secrets 覆盖:至少 32 字节的随机串",
    "AccessTokenMinutes": 10,
    "RefreshTokenDays": 14
  }
}
dotnet user-secrets init
# 生成 32 字节随机密钥(PowerShell)
$k = [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
dotnet user-secrets set "Jwt:SigningKey" $k
2. 实体与数据库上下文
using Microsoft.EntityFrameworkCore;

public class User
{
    public int Id { get; set; }
    public string UserName { get; set; } = string.Empty;
    public string PasswordHash { get; set; } = string.Empty;   // PHC 格式字符串,含算法与参数
    public bool IsActive { get; set; } = true;
    // 改密码 / 封号时自增,使所有已签发的 Access Token 立即失效
    public int SessionVersion { get; set; }
    public List<UserRole> UserRoles { get; set; } = [];

    // MFA
    public string? TotpSecret { get; set; }
    public bool TotpEnabled { get; set; }
}

public class Role
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;           // Admin / User / Auditor
    public List<UserRole> UserRoles { get; set; } = [];
}

public class UserRole
{
    public int UserId { get; set; }
    public User User { get; set; } = null!;
    public int RoleId { get; set; }
    public Role Role { get; set; } = null!;
}

// 一个订单,带 OwnerId —— 水平越权防御的关键字段
public class Order
{
    public int Id { get; set; }
    public int OwnerId { get; set; }
    public string Product { get; set; } = string.Empty;
    public decimal Amount { get; set; }
}

public class RefreshToken
{
    public int Id { get; set; }
    public int UserId { get; set; }
    public string TokenHash { get; set; } = string.Empty;      // 只存哈希,不存明文
    public DateTimeOffset ExpiresAt { get; set; }
    public DateTimeOffset? RevokedAt { get; set; }
    public DateTimeOffset? UsedAt { get; set; }                // 用于重放检测
    // 令牌家族:重放检测命中时,撤销同家族全部令牌
    public string FamilyId { get; set; } = Guid.NewGuid().ToString("N");
}

public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<User> Users => Set<User>();
    public DbSet<Role> Roles => Set<Role>();
    public DbSet<UserRole> UserRoles => Set<UserRole>();
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<RefreshToken> RefreshTokens => Set<RefreshToken>();

    protected override void OnModelCreating(ModelBuilder b)
    {
        b.Entity<User>().HasIndex(u => u.UserName).IsUnique();
        b.Entity<Role>().HasIndex(r => r.Name).IsUnique();
        b.Entity<UserRole>().HasKey(ur => new { ur.UserId, ur.RoleId });
        b.Entity<RefreshToken>().HasIndex(t => t.TokenHash).IsUnique();
        b.Entity<Order>().HasIndex(o => o.OwnerId);
        b.Entity<Order>().Property(o => o.Amount).HasPrecision(18, 2);
    }
}
3. 密码哈希与令牌服务
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Security.Cryptography;
using System.Text;
using Microsoft.IdentityModel.Tokens;

public sealed class JwtOptions
{
    public const string SectionName = "Jwt";
    public string Issuer { get; set; } = string.Empty;
    public string Audience { get; set; } = string.Empty;
    public string SigningKey { get; set; } = string.Empty;
    public int AccessTokenMinutes { get; set; } = 10;
    public int RefreshTokenDays { get; set; } = 14;
}

public static class PasswordHasher
{
    private const int SaltSize = 16, KeySize = 32, Iterations = 600_000;

    public static string Hash(string password)
    {
        var salt = RandomNumberGenerator.GetBytes(SaltSize);
        var key = Rfc2898DeriveBytes.Pbkdf2(password, salt, Iterations, HashAlgorithmName.SHA256, KeySize);
        return $"pbkdf2-sha256${Iterations}${Convert.ToBase64String(salt)}${Convert.ToBase64String(key)}";
    }

    public static bool Verify(string password, string stored)
    {
        var p = stored.Split('$');
        if (p.Length != 4 || p[0] != "pbkdf2-sha256" || !int.TryParse(p[1], out var it)) return false;
        try
        {
            var salt = Convert.FromBase64String(p[2]);
            var expected = Convert.FromBase64String(p[3]);
            var actual = Rfc2898DeriveBytes.Pbkdf2(password, salt, it, HashAlgorithmName.SHA256, expected.Length);
            return CryptographicOperations.FixedTimeEquals(actual, expected);
        }
        catch (FormatException) { return false; }
    }
}

public sealed class TokenService(IOptions<JwtOptions> options)
{
    private readonly JwtOptions _opt = options.Value;

    public (string Token, DateTimeOffset ExpiresAt) CreateAccessToken(
        User user, IEnumerable<string> roles, string sessionVersion)
    {
        var now = DateTimeOffset.UtcNow;
        var expires = now.AddMinutes(_opt.AccessTokenMinutes);

        var claims = new List<Claim>
        {
            new(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
            new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString("N")),   // 便于黑名单与审计
            new(JwtRegisteredClaimNames.Iat, now.ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer64),
            new(ClaimTypes.Name, user.UserName),
            new("sv", sessionVersion)                    // 会话版本,用于即时踢下线
        };
        claims.AddRange(roles.Select(r => new Claim(ClaimTypes.Role, r)));

        var creds = new SigningCredentials(
            new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_opt.SigningKey)),
            SecurityAlgorithms.HmacSha256);

        var jwt = new JwtSecurityToken(
            issuer: _opt.Issuer,
            audience: _opt.Audience,
            claims: claims,
            notBefore: now.UtcDateTime,
            expires: expires.UtcDateTime,
            signingCredentials: creds);

        return (new JwtSecurityTokenHandler().WriteToken(jwt), expires);
    }

    // Refresh Token 用高熵随机串,明文只发给客户端一次,服务端只存哈希
    public static string CreateRefreshToken() =>
        Convert.ToBase64String(RandomNumberGenerator.GetBytes(64));

    public static string Sha256(string value) =>
        Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(value)));

    public DateTimeOffset RefreshExpiry() => DateTimeOffset.UtcNow.AddDays(_opt.RefreshTokenDays);
}
4. 认证与授权策略注册
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<JwtOptions>(builder.Configuration.GetSection(JwtOptions.SectionName));
var jwt = builder.Configuration.GetSection(JwtOptions.SectionName).Get<JwtOptions>()
          ?? throw new InvalidOperationException("缺少 Jwt 配置节");

builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseSqlite(builder.Configuration.GetConnectionString("Default") ?? "Data Source=secure.db"));

builder.Services.AddScoped<TokenService>();
builder.Services.AddScoped<IAuthorizationHandler, OrderOwnerHandler>();
builder.Services.AddHttpContextAccessor();
builder.Services.AddProblemDetails();

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true, ValidIssuer = jwt.Issuer,
            ValidateAudience = true, ValidAudience = jwt.Audience,
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwt.SigningKey)),
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30),                     // 默认 5 分钟太宽松
            ValidAlgorithms = [SecurityAlgorithms.HmacSha256],         // 防算法混淆
            NameClaimType = ClaimTypes.Name,
            RoleClaimType = ClaimTypes.Role
        };
        o.MapInboundClaims = false;   // 保留原始 claim 名(sub/jti),避免被映射成微软长 URI
    });

builder.Services.AddAuthorizationBuilder()
    // 默认安全:凡未显式标注的终结点都要求已认证(避免「忘了加 [Authorize]」)
    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build())
    .AddPolicy("AdminOnly", p => p.RequireRole("Admin"))
    .AddPolicy("AuditorOrAdmin", p => p.RequireRole("Auditor", "Admin"))
    // 资源级策略:不仅要求已认证,还要通过 OrderOwnerHandler 的归属校验
    .AddPolicy("OrderOwner", p => p
        .RequireAuthenticatedUser()
        .AddRequirements(new OrderOwnerRequirement()));

var app = builder.Build();

// 中间件顺序:异常处理 → 路由 → 认证 → 授权 → 终结点
app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseAuthentication();      // 必须在 UseAuthorization 之前
app.UseAuthorization();
5. 资源级授权处理器(水平越权的服务端防线)
// 需求:仅订单所有者或 Admin 可访问该订单
public sealed class OrderOwnerRequirement : IAuthorizationRequirement;

public sealed class OrderOwnerHandler(AppDbContext db)
    : AuthorizationHandler<OrderOwnerRequirement, Order>
{
    protected override async Task HandleRequirementAsync(
        AuthorizationHandlerContext context, OrderOwnerRequirement requirement, Order order)
    {
        // 管理员放行
        if (context.User.IsInRole("Admin"))
        {
            context.Succeed(requirement);
            return;
        }

        var sub = context.User.FindFirst(System.IdentityModel.Tokens.Jwt.JwtRegisteredClaimNames.Sub)?.Value
                  ?? context.User.FindFirst(System.Security.Claims.ClaimTypes.NameIdentifier)?.Value;

        if (int.TryParse(sub, out var userId) && order.OwnerId == userId)
        {
            context.Succeed(requirement);
        }
        // 不调用 context.Fail():让其他处理器仍有机会成功,且失败一律走 403
    }
}
6. 会话版本校验(即时踢下线)
// 在认证之后插入:比对令牌里的 sv 与数据库里的 SessionVersion
app.Use(async (ctx, next) =>
{
    if (ctx.User.Identity?.IsAuthenticated == true)
    {
        var sv = ctx.User.FindFirst("sv")?.Value;
        var sub = ctx.User.FindFirst(JwtRegisteredClaimNames.Sub)?.Value;

        if (!int.TryParse(sub, out var userId) || sv is null)
        {
            ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
            return;
        }

        var db = ctx.RequestServices.GetRequiredService<AppDbContext>();
        // 只取需要的两列,避免过度取数
        var current = await db.Users.AsNoTracking()
            .Where(u => u.Id == userId)
            .Select(u => new { u.SessionVersion, u.IsActive })
            .FirstOrDefaultAsync(ctx.RequestAborted);

        if (current is null || !current.IsActive || current.SessionVersion.ToString() != sv)
        {
            ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await ctx.Response.WriteAsJsonAsync(new { error = "会话已失效,请重新登录" });
            return;
        }
    }
    await next();
});
7. 认证终结点(登录 / 刷新 / 登出)
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using Microsoft.AspNetCore.Authorization;
using Microsoft.EntityFrameworkCore;

var auth = app.MapGroup("/api/auth").WithTags("Auth").AllowAnonymous();

// ---- 登录 ----
auth.MapPost("/login", async (LoginRequest req, AppDbContext db, TokenService tokens, CancellationToken ct) =>
{
    var user = await db.Users
        .Include(u => u.UserRoles).ThenInclude(ur => ur.Role)
        .FirstOrDefaultAsync(u => u.UserName == req.UserName, ct);

    // 用户不存在时也走一次哈希验证,抹平响应时间差异,避免账号枚举
    var hash = user?.PasswordHash ?? PasswordHasher.Hash("dummy-for-timing");
    var ok = PasswordHasher.Verify(req.Password, hash) && user is { IsActive: true };

    if (!ok)
    {
        // 统一文案,不区分「用户名不存在」与「密码错误」
        return TypedResults.Problem(statusCode: StatusCodes.Status401Unauthorized,
            title: "用户名或密码错误");
    }

    var roles = user!.UserRoles.Select(ur => ur.Role.Name).ToList();
    var (accessToken, expiresAt) = tokens.CreateAccessToken(user, roles, user.SessionVersion.ToString());

    // Refresh Token:明文只返回给客户端,服务端只存 SHA-256
    var refreshPlain = TokenService.CreateRefreshToken();
    var familyId = Guid.NewGuid().ToString("N");
    db.RefreshTokens.Add(new RefreshToken
    {
        UserId = user.Id,
        TokenHash = TokenService.Sha256(refreshPlain),
        ExpiresAt = tokens.RefreshExpiry(),
        FamilyId = familyId
    });
    await db.SaveChangesAsync(ct);

    return TypedResults.Ok(new TokenResponse(accessToken, expiresAt, refreshPlain, roles));
})
.Produces<TokenResponse>()
.ProducesProblem(StatusCodes.Status401Unauthorized);

// ---- 刷新(轮换 + 重放检测)----
auth.MapPost("/refresh", async (RefreshRequest req, AppDbContext db, TokenService tokens, CancellationToken ct) =>
{
    var hash = TokenService.Sha256(req.RefreshToken);
    var row = await db.RefreshTokens.FirstOrDefaultAsync(t => t.TokenHash == hash, ct);

    if (row is null || row.RevokedAt is not null || row.ExpiresAt <= DateTimeOffset.UtcNow)
        return TypedResults.Problem(statusCode: StatusCodes.Status401Unauthorized, title: "刷新令牌无效");

    // 重放检测:已被使用过的令牌再次出现 ⇒ 判定泄露,撤销整个家族
    if (row.UsedAt is not null)
    {
        var family = await db.RefreshTokens.Where(t => t.FamilyId == row.FamilyId).ToListAsync(ct);
        foreach (var t in family) t.RevokedAt = DateTimeOffset.UtcNow;
        await db.SaveChangesAsync(ct);
        return TypedResults.Problem(statusCode: StatusCodes.Status401Unauthorized,
            title: "检测到刷新令牌重放,已撤销该会话全部令牌,请重新登录");
    }

    var user = await db.Users
        .Include(u => u.UserRoles).ThenInclude(ur => ur.Role)
        .FirstOrDefaultAsync(u => u.Id == row.UserId, ct);
    if (user is null || !user.IsActive)
        return TypedResults.Problem(statusCode: StatusCodes.Status401Unauthorized, title: "账号不可用");

    // 作废旧令牌,签发同家族的新令牌
    row.UsedAt = DateTimeOffset.UtcNow;
    row.RevokedAt = DateTimeOffset.UtcNow;

    var newPlain = TokenService.CreateRefreshToken();
    db.RefreshTokens.Add(new RefreshToken
    {
        UserId = user.Id,
        TokenHash = TokenService.Sha256(newPlain),
        ExpiresAt = tokens.RefreshExpiry(),
        FamilyId = row.FamilyId                 // 继承家族,便于一次性全撤销
    });
    await db.SaveChangesAsync(ct);

    var roles = user.UserRoles.Select(ur => ur.Role.Name).ToList();
    var (accessToken, expiresAt) = tokens.CreateAccessToken(user, roles, user.SessionVersion.ToString());
    return TypedResults.Ok(new TokenResponse(accessToken, expiresAt, newPlain, roles));
});

// ---- 登出(撤销当前刷新令牌家族)----
auth.MapPost("/logout", async (RefreshRequest req, AppDbContext db, CancellationToken ct) =>
{
    var hash = TokenService.Sha256(req.RefreshToken);
    var row = await db.RefreshTokens.FirstOrDefaultAsync(t => t.TokenHash == hash, ct);
    if (row is not null)
    {
        var family = await db.RefreshTokens.Where(t => t.FamilyId == row.FamilyId).ToListAsync(ct);
        foreach (var t in family) t.RevokedAt ??= DateTimeOffset.UtcNow;
        await db.SaveChangesAsync(ct);
    }
    return TypedResults.NoContent();     // 无论令牌是否存在都返回 204,避免探测
});

// ---- 改密码:递增 SessionVersion 让所有旧 Access Token 立即失效 ----
auth.MapPost("/change-password", async (ChangePasswordRequest req, AppDbContext db,
    HttpContext http, CancellationToken ct) =>
{
    var sub = http.User.FindFirst(JwtRegisteredClaimNames.Sub)?.Value;
    if (!int.TryParse(sub, out var userId)) return TypedResults.Unauthorized();

    var user = await db.Users.FirstOrDefaultAsync(u => u.Id == userId, ct);
    if (user is null) return TypedResults.Unauthorized();
    if (!PasswordHasher.Verify(req.CurrentPassword, user.PasswordHash))
        return TypedResults.Problem(statusCode: StatusCodes.Status400BadRequest, title: "当前密码不正确");

    user.PasswordHash = PasswordHasher.Hash(req.NewPassword);
    user.SessionVersion++;                            // ⇐ 关键:踢掉所有其他会话

    // 同时撤销全部刷新令牌
    var tokensOfUser = await db.RefreshTokens
        .Where(t => t.UserId == userId && t.RevokedAt == null).ToListAsync(ct);
    foreach (var t in tokensOfUser) t.RevokedAt = DateTimeOffset.UtcNow;

    await db.SaveChangesAsync(ct);
    return TypedResults.NoContent();
}).RequireAuthorization();      // 覆盖组上的 AllowAnonymous
8. 业务终结点:垂直 + 水平越权双重防御
var orders = app.MapGroup("/api/orders").WithTags("Orders").RequireAuthorization();

// 只读自己的订单:数据层强制带 OwnerId,这是水平越权的最后防线
orders.MapGet("/", async (AppDbContext db, HttpContext http, CancellationToken ct) =>
{
    var userId = int.Parse(http.User.FindFirst(JwtRegisteredClaimNames.Sub)!.Value);
    var list = await db.Orders.AsNoTracking()
        .Where(o => o.OwnerId == userId)                 // ⇐ 归属条件写在查询里,不靠内存过滤
        .Select(o => new OrderDto(o.Id, o.Product, o.Amount))
        .ToListAsync(ct);
    return TypedResults.Ok(list);
});

// 读单个订单:走资源级授权策略,非本人且非 Admin → 403
orders.MapGet("/{id:int}", async (int id, AppDbContext db, IAuthorizationService authz,
    HttpContext http, CancellationToken ct) =>
{
    var order = await db.Orders.AsNoTracking().FirstOrDefaultAsync(o => o.Id == id, ct);

    // 先做授权判定再决定是否暴露资源存在性
    if (order is null) return TypedResults.NotFound();

    var result = await authz.AuthorizeAsync(http.User, order, "OrderOwner");
    // 越权时返回 404 而非 403,避免泄露「该 ID 存在」
    return result.Succeeded
        ? TypedResults.Ok(new OrderDto(order.Id, order.Product, order.Amount))
        : TypedResults.NotFound();
});

// 创建订单:OwnerId 一律取自令牌,绝不接受客户端传入
orders.MapPost("/", async (CreateOrderRequest req, AppDbContext db, HttpContext http, CancellationToken ct) =>
{
    var userId = int.Parse(http.User.FindFirst(JwtRegisteredClaimNames.Sub)!.Value);
    var order = new Order { OwnerId = userId, Product = req.Product, Amount = req.Amount };
    db.Orders.Add(order);
    await db.SaveChangesAsync(ct);
    return TypedResults.Created($"/api/orders/{order.Id}", new OrderDto(order.Id, order.Product, order.Amount));
});

// 垂直越权防御:管理端点显式声明 AdminOnly 策略
app.MapGet("/api/admin/orders", async (AppDbContext db, CancellationToken ct) =>
    TypedResults.Ok(await db.Orders.AsNoTracking()
        .Select(o => new OrderDto(o.Id, o.Product, o.Amount)).ToListAsync(ct)))
   .RequireAuthorization("AdminOnly")
   .WithTags("Admin");
9. 数据传输对象
public sealed record LoginRequest(string UserName, string Password);
public sealed record RefreshRequest(string RefreshToken);
public sealed record ChangePasswordRequest(string CurrentPassword, string NewPassword);
public sealed record CreateOrderRequest(string Product, decimal Amount);
public sealed record OrderDto(int Id, string Product, decimal Amount);
public sealed record TokenResponse(string AccessToken, DateTimeOffset ExpiresAt,
    string RefreshToken, IReadOnlyList<string> Roles);

public partial class Program { }   // 供集成测试引用
10. 客户端调用示例
# 登录
curl -X POST https://localhost:5001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"userName":"alice","password":"Correct-Horse-Battery-Staple-2026"}'
# → {"accessToken":"eyJ...","expiresAt":"...","refreshToken":"9f2...","roles":["User"]}

# 访问受保护资源(把令牌放 Authorization 头,不要放 URL 查询串)
curl https://localhost:5001/api/orders -H "Authorization: Bearer eyJ..."

# 刷新(注意:返回新的 refreshToken,旧的必须丢弃)
curl -X POST https://localhost:5001/api/auth/refresh \
  -H "Content-Type: application/json" -d '{"refreshToken":"9f2..."}'

常见坑

1. 把令牌放 URL 里(?token=xxx):会进浏览器历史、Referer 头、代理与服务器访问日志。必须放 Authorization 头或 HttpOnly Cookie。

2. 用 JwtSecurityTokenHandler 的默认 MapInboundClaims:sub 会被映射成 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier,按 "sub" 取值会拿到 null。设 MapInboundClaims = false 或按映射后的名字取。

3. ClockSkew 用默认 5 分钟:10 分钟有效的令牌实际能用 15 分钟。

4. 校验参数漏项:只验签名不验 iss/aud/exp,等于接受任何用同一密钥签发的令牌(包括别的环境签的)。OAuth 2.0 访问令牌应校验 iss、exp、aud、sub、client_id、iat、jti。

5. Refresh Token 明文入库:数据库泄露即等于永久的账号访问权。只存哈希。

6. 刷新时不作废旧令牌:等于给了攻击者一个永不过期的凭证;且无法做重放检测。

7. IsActive 只在登录时检查:账号被封禁后,旧 Access Token 在过期前仍然可用。用 SessionVersion 或黑名单补齐。

8. [Authorize] 只在控制器上写:新增的终结点忘了加就默认公开。用 SetFallbackPolicy 做默认拒绝。

9. 信任客户端传的 ownerId / userId:这是水平越权最常见的成因。归属字段一律取自令牌。

10. 登录失败提示区分了「用户不存在」与「密码错误」:给攻击者提供了账号枚举接口。

11. 只在前端隐藏管理菜单:后端没有任何校验,改个请求就进去了。这是垂直越权的教科书案例。

12. 密钥写在 appsettings.json 并提交:见 后端-03-ASPNET-Core 的「为什么不能把连接字符串提交进仓库」。

13. ValidAlgorithms 不设白名单:给算法混淆留下空间。

14. 密码哈希用 == 比较:会因短路比较泄露时序信息。必须用固定时间比较。

九、常见漏洞与防御对照表

漏洞成因后果防御
明文 / 快速哈希存密码用 MD5、SHA-1、裸 SHA-256库泄露即等于密码泄露Argon2id / scrypt / bcrypt(cost≥10) / PBKDF2(≥600k)
无盐哈希未加随机盐彩虹表命中、可识别相同密码每用户唯一随机盐 ≥ 128 位
时序攻击用 == 比较哈希或令牌逐字节猜出哈希CryptographicOperations.FixedTimeEquals
会话固定登录后沿用旧会话 ID攻击者预置的 ID 变成合法凭证登录成功后作废并重签会话 ID
Cookie 缺 HttpOnly默认配置未加一次 XSS 即可窃取会话认证 Cookie 一律 HttpOnly; Secure; SameSite
Cookie 缺 Secure本地开发配置带到生产明文网络中会话被嗅探生产强制 HTTPS + Secure
Domain=.example.com图方便共享到子域任意子域(含被接管的)可读会话省略 Domain,仅当前域
令牌存 localStorage图方便给前端读XSS 直接带走令牌,可用刷新令牌续命HttpOnly Cookie + CSRF Token,或 BFF 模式
无 CSRF 防御Cookie 自动携带第三方站点可代用户发起写操作SameSite + CSRF Token(双提交或同步器令牌)+ 写操作只用 POST/PUT/DELETE
alg: none库接受无签名令牌任意伪造身份升级库;显式拒绝 none
算法混淆按 header 的 alg 动态选算法,把公钥当 HMAC 密钥用公开公钥伪造令牌算法白名单,非对称与对称不混用
信任 header 中的密钥从 jwk/jku/x5u 取验证密钥攻击者用自己的密钥签名密钥来自带外固定来源;kid 仅在已配置密钥集内选择
iss/aud 不校验只验签名跨环境、跨服务令牌互相可用严格校验 iss + aud + exp + nbf
用 ID Token 访问 API混淆令牌用途权限边界错乱Access Token 只给资源服务器;ID Token 只给客户端
JWT 无法撤销无状态设计改密码/封号后旧令牌仍有效短过期 + 刷新令牌 + SessionVersion 或 jti 黑名单
刷新令牌不轮换一签到过期泄露后长期可用轮换 + 重放检测 + 家族级撤销
Refresh Token 明文入库图省事库泄露 = 永久访问权只存哈希
水平越权(IDOR)只按主键查询,无归属校验遍历 ID 读/改他人数据查询强制带归属条件;越权返回 404
垂直越权只在前端隐藏功能低权限用户执行管理操作每端点显式策略 + SetFallbackPolicy 默认拒绝
账号枚举登录/注册/找回密码的提示或响应时间可区分攻击者批量收集有效账号统一提示 + 恒定响应时间
无登录限流无失败计数可无限撞库账号 + IP 多维限流、指数退避、验证码
密码重置令牌长期有效 / 可复用令牌不过期、不一次性邮件泄露即永久可改密一次性、≤15 分钟、绑定账号与用途、改密后作废
OTP 可重放同一 TOTP 在窗口内被接受多次30 秒内窃听的验证码可用成功验证后立即标记该 OTP 已用
OTP 延迟窗口过大允许多个时间步可用时间窗变长最多允许 1 个时间步的网络延迟
使用 password 授权类型沿用旧流程客户端持有用户明文密码禁止;改用授权码 + PKCE
使用隐式流程沿用旧 SPA 方案令牌暴露在 URL 与历史记录授权码 + PKCE(S256)
PKCE 用 plain图方便verifier 明文出现在授权请求中强制 S256
重定向 URI 模糊匹配用通配/前缀匹配授权码被重定向到攻击者域名精确字符串匹配;禁止开放重定向
日志记录令牌/密码调试残留日志系统成为凭据泄露源敏感字段脱敏;只记 jti 等标识

练习题

1. 下面这段登录逻辑有 4 处安全缺陷,请逐条指出并给出修复代码:

app.MapPost("/login", async (LoginRequest req, AppDbContext db) =>
{
    var user = await db.Users.FirstOrDefaultAsync(u => u.UserName == req.UserName);
    if (user is null) return Results.BadRequest("该用户名不存在");
    if (user.PasswordHash != Sha256(req.Password)) return Results.BadRequest("密码错误");

    var token = CreateJwt(user);
    return Results.Ok(new { token });
});

2. 某对比价应用把 Access Token 存在 localStorage 里,有效期 24 小时且没有刷新机制。请分析两处风险,并给出改进后的完整方案(包括令牌存放位置、有效期、刷新策略、CSRF 防御)。

3. 为什么 SameSite=Lax 不能替代 CSRF Token?请举一个 Lax 下仍能发起跨站请求的具体场景,并说明防御方式。

4. 实现一个 TOTP 验证函数(不依赖第三方库),要求:接受当前时间步与上一个时间步的验证码,且同一验证码成功验证后不能被再次接受。给出关键代码与至少一条 RFC 6238 的测试向量作为验证依据。

5. 有 Project 与 ProjectMember(含 role 字段:owner/editor/viewer)。要求「owner 可删除项目,editor 可编辑,viewer 只读,Admin 可做任何事」。请分别用 RBAC 和 ReBAC 的思路说明实现方式,并分析当项目数 100 万、成员关系 5000 万时哪种更合适。

FAQ

前后端分离时,到底该用 Cookie 还是 Bearer Token?

判据是「谁能接触令牌」。如果浏览器端要直接调用 API,优先 HttpOnly Cookie + CSRF Token(令牌对 JS 不可见,XSS 偷不走);如果是移动 App、服务间调用、或第三方开发者调用你的开放 API,用 Bearer Token(这些环境下没有「浏览器自动携带」的问题,也就没有 CSRF 面)。安全要求最高的 Web 场景选 BFF 模式:令牌只存在后端,浏览器只拿会话 Cookie。

JWT 是不是比 Session 更安全?

不是。安全性取决于实现,不是格式。JWT 的优势是跨实例免共享存储和自包含;代价是难以主动失效、载荷可读、以及一个常见陷阱——很多人为了「无状态」把权限信息全塞进令牌,结果权限变更后要等令牌过期才生效。Session 的优势恰恰是服务端完全可控。选型要看「是否需要即时撤销」与「是否有共享存储可用」。

我用的是 Auth0 之类的托管服务,还需要关心这些细节吗?

需要,但分工不同。托管服务负责授权服务器那一侧(PKCE 支持、密钥轮换、元数据发布);你负责资源服务器这一侧:必须显式校验令牌(签名、iss、aud、exp)、配置算法白名单、做好资源级授权(水平越权完全是你的责任)、以及正确的 Cookie/CSRF 设置。把令牌交给托管服务不等于把授权也交出去了。

密码哈希参数调高之后登录明显变慢,怎么办?

先算清楚预算:600,000 次 PBKDF2 在常见服务器上大约 100–200 ms,这个量级对登录接口是正常的。如果确实超预算,有三个方向:① 换 Argon2id 并用内存换时间(如 m=19456, t=2 比高迭代 PBKDF2 更快且更抗 GPU);② 对登录接口单独限流,防止攻击者用登录请求打满 CPU(DoS);③ 把哈希验证放到独立的线程池/服务里,避免阻塞请求线程。不要为了性能降低到不安全的参数。

越权失败时应该返回 403 还是 404?

默认用 403(语义正确,且能帮合法用户理解问题)。但当「资源是否存在」本身是敏感信息时——比如订单号、发票号、用户 ID 这类可枚举的标识——应当返回 404,避免攻击者通过 403/404 的差异枚举出系统里有哪些 ID。这是一个「语义正确」与「信息最小化」之间的取舍,需要在接口文档里明确约定。

相关笔记

  • 后端-01-HTTP与RESTfulAPI设计 —— 401/403 的语义、WWW-Authenticate 头、状态码约定。
  • 后端-03-ASPNET-Core —— 本文的中间件顺序、DI 生命周期、配置与用户机密都建立在那篇之上。
  • 后端-09-后端安全与性能 —— OWASP Top 10 全貌、注入与 XSS、限流与缓存。
  • 前端-04-浏览器与HTTP —— Cookie 的收发规则、同源策略与跨域,理解 CSRF 与 SameSite 的前提。
  • 计算机网络 —— HTTPS/TLS 如何保护令牌在传输中不被窃听与篡改。
  • 数据库原理 —— 密码哈希与令牌表涉及的索引、唯一约束与事务。
  • CSharp-05-异步编程 —— 本文实现中 async/await 与 CancellationToken 的传播。

参考来源

  • ASP.NET Core 身份验证概述(方案、处理程序、挑战与禁止):https://learn.microsoft.com/zh-cn/aspnet/core/security/authentication/?view=aspnetcore-10.0
  • ASP.NET Core 中的授权简介:https://learn.microsoft.com/zh-cn/aspnet/core/security/authorization/introduction?view=aspnetcore-10.0
  • ASP.NET Core 中基于角色的授权:https://learn.microsoft.com/zh-cn/aspnet/core/security/authorization/roles?view=aspnetcore-10.0
  • ASP.NET Core 中基于策略的授权(回退策略、要求与处理程序):https://learn.microsoft.com/zh-cn/aspnet/core/security/authorization/policies?view=aspnetcore-10.0
  • 在 ASP.NET Core 中配置 JWT 持有者身份验证(须校验的声明、MapInboundClaims):https://learn.microsoft.com/zh-cn/aspnet/core/security/authentication/configure-jwt-bearer-authentication?view=aspnetcore-10.0
  • 在没有 ASP.NET Core Identity 的情况下使用 Cookie 身份验证(ValidatePrincipal、Cookie 策略、ASP.NET Core 10 的 API 端点行为变更):https://learn.microsoft.com/zh-cn/aspnet/core/security/authentication/cookie?view=aspnetcore-10.0
  • ASP.NET Core 中的一般数据保护条例(GDPR)支持(IsEssential 与 Cookie 同意):https://learn.microsoft.com/zh-cn/aspnet/core/security/gdpr?view=aspnetcore-10.0
  • Rfc2898DeriveBytes 类(PBKDF2 与 Pbkdf2 静态方法):https://learn.microsoft.com/zh-cn/dotnet/api/system.security.cryptography.rfc2898derivebytes
  • Microsoft 标识平台和 OAuth 2.0 授权代码流(PKCE 参数、令牌响应、刷新令牌):https://learn.microsoft.com/zh-cn/entra/identity-platform/v2-oauth2-auth-code-flow
  • OWASP 密码存储备忘单(Argon2id / scrypt / bcrypt / PBKDF2 参数、加盐与胡椒、旧哈希升级):https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html
  • OWASP JSON Web Token 备忘单(alg: none、密钥类型混淆、不可信密钥来源、拒绝列表与 JWE):https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_Cheat_Sheet.html
  • OWASP 会话管理备忘单:https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
  • OWASP 授权备忘单:https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
  • OWASP 身份验证备忘单:https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
  • OWASP 忘记密码备忘单(重置令牌的一次性与有效期):https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html
  • OWASP 不安全的直接对象引用预防备忘单(水平越权/IDOR):https://cheatsheetseries.owasp.org/cheatsheets/Insecure_Direct_Object_Reference_Prevention_Cheat_Sheet.html
  • OWASP 多因素身份验证备忘单:https://cheatsheetseries.owasp.org/cheatsheets/Multifactor_Authentication_Cheat_Sheet.html
  • OWASP 跨站请求伪造预防备忘单:https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
  • OWASP 凭据填充攻击预防备忘单(登录限流与锁定策略):https://cheatsheetseries.owasp.org/cheatsheets/Credential_Stuffing_Prevention_Cheat_Sheet.html
  • OWASP Top 10 项目主页:https://owasp.org/www-project-top-ten/
  • RFC 6749:The OAuth 2.0 Authorization Framework(角色、四种授权类型、授权码一次性与 10 分钟有效期):https://www.rfc-editor.org/rfc/rfc6749.html
  • RFC 7519:JSON Web Token (JWT)(三段式结构、iss/sub/aud/exp/nbf/iat/jti):https://www.rfc-editor.org/rfc/rfc7519.html
  • RFC 6238:TOTP(时间步长 30 秒、验证窗口、OTP 不得重复接受、测试向量):https://www.rfc-editor.org/rfc/rfc6238.html
  • RFC 4226:HOTP(HMAC 构造与动态截断):https://www.rfc-editor.org/rfc/rfc4226.html
  • RFC 7636:PKCE(code_verifier / code_challenge 与 S256):https://www.rfc-editor.org/rfc/rfc7636.html
  • RFC 9700:OAuth 2.0 Security Best Current Practice(禁止 password 授权、弃用隐式流程、刷新令牌轮换的强制要求):https://www.rfc-editor.org/rfc/rfc9700.html
  • RFC 7515:JSON Web Signature (JWS):https://www.rfc-editor.org/rfc/rfc7515.html
  • RFC 7518:JSON Web Algorithms (JWA):https://www.rfc-editor.org/rfc/rfc7518.html
  • MDN:HTTP Cookie 指南(HttpOnly / Secure / SameSite 的语义与限制):https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Guides/Cookies
  • MDN:Set-Cookie 响应头(Domain、Path、Max-Age 等属性的逐项说明):https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Reference/Headers/Set-Cookie
  • MDN:Authorization 请求头:https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Reference/Headers/Authorization
  • MDN:Web Authentication API(Passkey / WebAuthn 的浏览器接口):https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Authentication_API