第 3 篇结束时,接口虽然有了数据库,但仍然是谁都能调。加鉴权的第一反应通常是「给每个接口加个判断」,我就这么干过:登录接口发一串令牌,其它接口检查这个字符串对不对。能跑,/api/me 带着令牌返回用户名,看起来成了。问题是这串令牌里明明白白写着用户名,签名只是拼在后面的一串十六进制,客户端改掉用户名、保留签名,服务端如果只比较「用户名对不对」而忘了重算签名,就能冒充任何人。
这类问题不是代码写得糙,而是没把两件事分开:认证(authentication)回答「你是谁」,授权(authorization)回答「你能干什么」。把它们混在一个 if 里,最后既不知道身份从哪来,也不知道权限规则写在哪。再往后还有一堆现实问题:令牌多久过期、能不能主动吊销、密钥换了旧令牌怎么办、多实例部署时每个实例的密钥要不要一致。
这篇先用手写的 HMAC 令牌把流程跑通,看清每一步在做什么,再讲生产环境为什么通常换成 JWT 或 Cookie 会话,以及授权的规则该落在哪一层。登录和 /api/me 的返回都是本机实测;JWT 库、Cookie 中间件的实际行为没有跑过,会明确标出。
先看那串令牌:登录与校验的最小闭环
令牌(token)就是服务端发给客户端的一张凭证,之后每次请求带上它,服务端据此确认身份。这里不用任何第三方库,System.Security.Cryptography 是框架自带的,项目不需要加包。核心只有两个方法:签发和校验。
依赖没有变化,还是 Web SDK 加 net8.0,不需要额外包:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
</Project>
构建和启动命令与前面一致:
dotnet build
dotnet run --no-launch-profile --urls "http://127.0.0.1:18082"
鉴权相关的东西只有两处,逻辑集中,方便替换成框架方案:
using System.Security.Cryptography;
using System.Text;
public class TokenService
{
private readonly byte[] _key;
public TokenService(IConfiguration cfg)
{
var secret = cfg["Auth:Key"] ?? "dev-only-key-change-me";
_key = Encoding.UTF8.GetBytes(secret);
}
public string Issue(string user)
{
var sig = Convert.ToHexString(
HMACSHA256.HashData(_key, Encoding.UTF8.GetBytes(user)))
.ToLowerInvariant();
return user + "." + sig;
}
public string? Validate(string token)
{
var parts = token.Split('.');
if (parts.Length != 2) return null;
var user = parts[0];
var expected = Convert.ToHexString(
HMACSHA256.HashData(_key, Encoding.UTF8.GetBytes(user)))
.ToLowerInvariant();
var given = Encoding.UTF8.GetBytes(parts[1]);
var want = Encoding.UTF8.GetBytes(expected);
if (!CryptographicOperations.FixedTimeEquals(given, want)) return null;
return user;
}
}
签发就是「把用户名和它的签名拼起来」,签名是用只有服务端知道的密钥算出来的。校验则是「收到令牌后自己再算一遍签名」,算出来一致才认。关键在于:客户端能改用户名,但改完算不出新签名,因为密钥不在客户端手里。所以校验时必须重算,不能只解析出用户名就信。
签名和加密是两回事。HMAC 只保证「内容没被改过」,不保证「内容看不见」:用户名仍然是明文,任何人拿到令牌都能直接读出来。所以令牌里不要放密码、手机号这类敏感字段。需要保密就再加一层加密,那是另一个话题,而且大多数场景根本不需要把敏感信息放进令牌。
把它接到管道里,需要三样东西:注册服务、一个读请求头的认证中间件、一个登录端点。中间件只负责「把身份放到当前请求上」,不负责判断权限:
builder.Services.AddSingleton<TokenService>();
var app = builder.Build();
app.Use(async (ctx, next) =>
{
var header = ctx.Request.Headers.Authorization.ToString();
if (header.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase))
{
var user = ctx.RequestServices.GetRequiredService<TokenService>
.Validate(header["Bearer ".Length..]);
if (user is not null) ctx.Items["user"] = user;
}
await next();
});
app.MapPost("/api/login", (LoginInput input, TokenService tokens) =>
input.User == "demo" && input.Pass == "demo"
? Results.Json(new { token = tokens.Issue(input.User) })
: Results.Json(new { error = "bad credentials" }, statusCode: 401));
app.MapGet("/api/me", (HttpContext ctx) =>
ctx.Items["user"] is string user
? Results.Json(new { user })
: Results.Json(new { error = "unauthorized" }, statusCode: 401));
app.Run();
public record LoginInput(string User, string Pass);
实测两步。先登录拿令牌,再带着令牌请求 /api/me:
curl.exe -s -X POST 127.0.0.1:18082/api/login -H "Content-Type: application/json" -d "{\"user\":\"demo\",\"pass\":\"demo\"}"
{"token":"demo.652b7fa18f06201754719d10507b6868d2aaa10b98c0a2acfb5c052181680813"}
curl.exe -s -i 127.0.0.1:18082/api/me -H "Authorization: Bearer demo.652b7fa18f06201754719d10507b6868d2aaa10b98c0a2acfb5c052181680813"
HTTP/1.1 200 OK
{"user":"demo"}
令牌的十六进制部分取决于密钥,我本机用的是一份本地密钥,所以你换个密钥跑出来的值会不同,格式和长度是一样的。这也提醒一件事:密钥不能写死在代码里提交到仓库,否则任何人拿到源码就能伪造令牌。
认证和授权:两件事,两个地方
把这两件事分开看,后面的选型会清楚很多:
很多 401 和 403 用错的地方,根子是把这三层混了。比如「查不到别人的订单」,正确的做法是查询时带上当前用户 id,返回 404 而不是 403,因为不该告诉对方「这条数据存在但你没权限」。而「非管理员不能删条目」这种规则,适合放在端点上统一判断,不用每条 SQL 都写一遍。
认证中间件的位置在第 2 篇讲过:必须在 UseAuthorization 之前。它的产物通常是一个「当前用户」对象,授权层读它,业务层也读它。上面的写法把用户名放进了 HttpContext.Items,这是最轻的方式;正式项目一般用框架的 HttpContext.User,这样能和现成的授权策略对接。
授权规则放哪一层,有个简单的分工:整组端点共用的规则(必须登录、必须是管理员)放在端点或分组上;单条数据的归属判断放在处理函数里,靠近查询;纯展示层的按钮隐藏放在前端,但不能当成权限,因为接口仍然可能被直接调用。三层都要有,缺一层就等于没有。
实际项目里最常见的错法是把「已登录」当成「有权限」。登录只证明这个人是谁,不代表他能看所有数据。特别是多租户系统,同一个接口对 A 公司返回 A 的数据、对 B 公司返回 B 的数据,这个过滤条件必须写进查询里,靠中间件拦不住。凡是「按用户过滤」的查询,都要有测试覆盖,否则越权不会报错,只会悄悄多返回几条,等到被人发现就已经晚了。
手写令牌和生产方案:什么时候该换
上面的实现能跑,但它只适合讲原理。和两种主流方案对比一下:
JWT(JSON Web Token)
把用户、过期时间、角色这些信息签进一段标准格式的字符串,服务端不存会话,验签即认。适合多服务、跨域、需要横向扩展的 API。代价是「签发后无法直接作废」,要吊销就得额外维护一张黑名单或版本号。
Cookie 会话
服务端存会话,浏览器只拿一个随机 id。能随时踢人、能改权限即时生效,浏览器自动携带,不用前端处理令牌。代价是要有共享存储(多实例),跨域麻烦,对纯 API 客户端不友好。
手写令牌介于两者之间:它像 JWT 一样无状态,但没有标准格式、没有过期字段、没有成熟的密钥轮换机制。规模上的判断:日活几千、单实例、内部服务,手写一套只要把密钥管好、把过期加上,也能用;一旦要多实例、要接第三方、要做细粒度权限,就该换 JWT 中间件;如果是同域网页、需要「立即踢下线」,Cookie 会话更合适。
生产用 JWT 的话,框架侧是 AddAuthentication().AddJwtBearer(...) 加 UseAuthentication(),校验签名、过期、颁发者这些都由中间件做,你不用自己解析字符串。签名算法一般选非对称的 RS256:私钥只留在签发服务,其它服务用公钥验签,泄露风险小很多。这部分本机没有实测,具体的包版本和配置项以你项目里的框架版本为准。
选 JWT 还要注意算法选择。有些旧教程用 HS256,也就是签发和验证共用一把密钥,任何能验签的服务都能伪造令牌。多服务场景应该用 RS256 这类非对称算法,私钥只在签发方,验证方只有公钥。另一个坑是不要相信令牌头里声明的算法,中间件要显式指定允许的算法,否则会出现算法混淆一类的攻击。
demo. 加 64 位十六进制,/api/me 带 Bearer 头返回 200。System.IdentityModel.Tokens.Jwt、AddJwtBearer、Cookie 认证中间件的实际输出均未在本机实测。授权的三种落点,别放错层
同一个「只有管理员能删」的需求,有三种写法,代价不同:
// 一、端点级:整条路由要求已登录
app.MapGet("/api/orders", () => Results.Json(new { ok = true }))
.RequireAuthorization();
// 二、策略级:把规则命名,端点只引用名字
builder.Services.AddAuthorization(o =>
o.AddPolicy("admin", p => p.RequireClaim("role", "admin")));
app.MapDelete("/api/items/{id:long}", (long id) => Results.NoContent())
.RequireAuthorization("admin");
// 三、过滤器级:需要读参数、写自定义响应时用它
app.MapDelete("/api/items/{id:long}", (long id) => Results.NoContent())
.AddEndpointFilter(async (invocation, next) =>
{
var ctx = invocation.HttpContext;
if (ctx.Items["user"] is not "admin")
return Results.Json(new { error = "forbidden" }, statusCode: 403);
return await next(invocation);
});
三种写法的分工:端点级最省事,适合「登录即可」;策略级把规则集中到一处,改规则只改注册那段,适合角色、声明这类通用判断;过滤器级能拿到路由参数和请求体,适合「只能删自己的」这种依赖具体数据的判断,但它写在管道里,业务代码可能看不到,团队要约定清楚。
注意上面第二种写法依赖框架的认证方案:RequireAuthorization("admin") 要能读到 role 声明,前提是认证中间件已经把声明放进 HttpContext.User。手写令牌只放了用户名,没有声明,所以这套策略接不上,只能用过滤器。这也是「手写令牌别上生产」的一个具体理由:它和框架的授权体系不兼容。
放错层的典型症状是「规则写了两遍」。端点要求管理员,处理函数里又判断一次管理员,改规则时漏掉一处,权限就出现缺口。正确的做法是:能放端点的放端点,能放策略的放策略,只有依赖单条数据归属的判断才进业务代码,而且只写一次。
鉴权出问题,先看这张表
鉴权故障有个特点:报错都长得很像,都是 401 或 403,但原因可能差得很远。按现象查更快:
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 带了令牌仍返回 401 | 请求头格式不对,缺 Bearer 前缀或大小写不一致 | 把服务端收到的原始 Authorization 头打出来 |
| 改一个字符令牌仍然通过 | 只解析了用户名,没有重算签名 | 看校验函数里有没有重新计算 HMAC |
| 重启后所有令牌失效 | 密钥是启动时随机生成的,或环境变量没配稳 | 检查密钥来源,确认每次启动读到的是同一个值 |
| 令牌永久有效,注销也拦不住 | 没有过期字段,也没有服务端吊销机制 | 看令牌内容里有没有过期时间 |
| 加了策略但完全不生效 | 没注册 AddAuthorization,或中间件顺序在端点之后 | 看注册代码和 UseAuthorization 的位置 |
| 多实例部署,部分请求 401 | 各实例的签名密钥不一致 | 对比各实例读到的配置值 |
| 令牌出现在访问日志里 | 放进了 URL 查询串,被日志完整记录 | 搜日志里的 token 字段,改成放请求头 |
| 签名比较偶尔「看起来」不安全 | 用了普通字符串相等,比较耗时会泄露位置信息 | 确认是否用了 FixedTimeEquals |
最后一条值得多说两句。普通的字符串比较遇到第一个不同字符就返回,耗时随「相同前缀的长度」变化。攻击者可以通过大量请求测出这个差异,一个字符一个字符地把签名试出来。这不是理论上的风险,在网络稳定、请求量足够时是可以测出来的。FixedTimeEquals 的写法是逐字节比较且不提前返回,耗时与内容无关。只要比较的是密钥相关的东西,就用它。
还有一个容易忽略的点:401 和 403 的语义不能混。401 是「你没证明身份」,通常带 WWW-Authenticate 头;403 是「身份确认了,但这事你不能干」。把「没登录」返回成 403,客户端不知道该去登录,体验和排查都会绕远路。
日志里记录鉴权失败时,不要记完整令牌,记前几位加长度就够了。完整令牌等于把凭证写进日志,任何能看日志的人都能冒用。审计真正需要的是「谁在什么时候从哪个地址试图访问什么」,不是令牌原文。
边界与代价:过期、刷新、轮换
上面那份实现为了对齐实测,只签了用户名,没有把过期时间放进去。这是一个真实的缺陷:令牌一旦泄露,永远有效。补法是把过期时间拼进被签名的内容,校验时先验签、再比时间:
public string Issue(string user, long ttlSeconds)
{
var expires = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + ttlSeconds;
var payload = user + "." + expires;
var sig = Convert.ToHexString(
HMACSHA256.HashData(_key, Encoding.UTF8.GetBytes(payload)))
.ToLowerInvariant();
return payload + "." + sig;
}
过期时间的长短是取舍。太长,泄露后窗口大;太短,用户频繁重新登录。常见做法是访问令牌几分钟到几小时,配一个刷新令牌(refresh token),它存在服务端、有效期更长、可以吊销。刷新令牌一旦被窃取,风险比访问令牌大,所以要绑定设备、限制使用次数、用一次就换新的(轮换)。
密钥轮换是另一个必须提前想的事。换密钥的那一刻,所有旧令牌都会失效,用户被集体登出。平滑的做法是同时保留新旧两把密钥:签发用新的,校验时先试新的、失败再试旧的,等旧令牌的最长有效期过去,再把旧密钥删掉。这个「双密钥过渡期」的做法任何方案都适用,JWT 也一样。
无状态的代价也要说清楚。JWT 一旦签发,服务端没有记录,想「立刻踢掉某个用户」就做不到,只能靠加黑名单或用户级版本号,这又引入了状态。需要即时吊销、用户量在百万以内、单服务的场景,服务端会话(Cookie 或会话表)反而简单。反过来,多服务、跨域、客户端是移动应用或第三方,JWT 的无状态优势才明显。
CORS 也是选型的一部分。浏览器跨域带 Cookie 需要配置凭据和同源策略,带 Authorization 头则要处理预检请求。纯 API 用令牌更省事,同域网页用 Cookie 更省事,这两句话基本能覆盖大多数项目的选择。
最后是密码本身。上面登录接口把 demo 和 demo 写死在代码里,只是为了演示。真实系统要存哈希,不要存明文,也不要用 MD5 这类已经不适合口令的算法。验证时同样用固定时间比较,别让密码校验成为另一个时序漏洞。
今天就能自验的五个练习
鉴权必须亲手改坏一次才知道哪里会漏,下面每条都能在本地验证:
- 登录拿到令牌,把它最后一位改掉,再请求
/api/me,确认返回 401。然后去掉签名校验那一行,重复请求,观察它变成了 200。这一步是为了看清「校验签名」到底防住了什么。 - 把请求头的
Bearer前缀去掉,只放令牌本身,观察服务端的行为,再检查中间件里StartsWith的判断。 - 重启服务但不改配置,用旧令牌再请求一次,确认仍然有效;然后改一下
Auth:Key再启动,确认旧令牌全部失效。 - 给
/api/me加一个RequireAuthorization(),启动项目,记录框架给出的报错,理解「策略需要认证方案」这件事。 - 把令牌放进查询串
?token=...,请求一次,然后在启动日志里找它,确认它被完整记录。这条是为了让你以后不敢这么传。
小结
下一篇讲后台任务。现在的接口都是「请求来了才干活」,但有些事不该让用户等着:发报表、清理过期数据、批量同步。这些活要放到请求之外跑,而一旦离开请求,第 3 篇讲的 scoped 生命周期就不再自动生效,后台服务里拿 DbContext 会直接踩坑。第 5 篇会把这个坑和实测日志一起讲清楚。
这篇的三句话总结:第一,认证和授权是两件事,认证确定身份、授权判断能不能干,数据归属的判断必须落到查询条件里;第二,手写 HMAC 令牌能讲清原理但不适合生产,多实例、要接第三方、要细粒度权限时换 JWT,需要即时吊销就用服务端会话;第三,签名比较用 FixedTimeEquals,令牌要有过期时间,密钥轮换留双密钥过渡期。