算年头.Net Core 2.1都已经是微软官方停止支持的老框架了但我发现直到今天还有不少老项目在它上面跑着而且最典型的需求之一就是“用JWT生成Token做身份认证”。不夸张地说JWT已经成了前后端分离架构下做认证的事实标准。这篇文章我不打算贴一大堆官方文档而是从一个做过的真实项目角度出发把这套东西从原理到落地再到排查问题完整拆开揉碎讲一遍。如果你正在维护一个.Net Core 2.1的老项目或者刚接手这样的代码又或者只是想搞明白JWT在服务端到底是怎么“验”的这篇文章都适合你。我会把Token生成、中间件配置、Claims设计、常见401/403问题一次讲清楚很多细节是官方文档里不会写的。1. 为什么要用JWT而不是Session很多从.Net Framework时代转过来的同学第一时间想的是以前用Session不也挺好的确实传统的Session认证方式在小规模单体应用里完全够用但它存在一个比较麻烦的先天问题——Session存储在服务器内存里客户端只保存一个SessionId。用户量一旦上来或者你需要横向扩容部署多台服务器Session就变成了一个坑这台机器登录的另一台机器不认识得专门去做Session共享比如用Redis存Session。这些工作能跑通但复杂度明显上去了。JWT的思路完全不同用户登录成功后服务器算出一个经过签名的Token把它直接返回给客户端。客户端之后的每一次请求在请求头里带上这个Token服务器只要验签通过就放行。服务器本身不存Token所以也就没有“分布式Session同步”这种烦恼。这种无状态的设计对于构建Web API、小程序后台、App接口尤其是前后端完全分离的项目非常友好。1.1 无状态认证为什么更适合现在的架构现在的项目很少是一个单体MVC走天下前端一个Vue或React应用后端一个Web API甚至后端还有好几个服务。这种情况下如果用Session会出现几个让人头疼的问题多端登录状态难以统一管理Web端、小程序、App各有一套SessionId处理起来很分裂。Session默认依赖Cookie传递但App或小程序里对Cookie的支持并不像浏览器那样“开箱即用”。服务端扩展时会话数据同步总是绕不开的额外工作。JWT把用户身份信息直接编码在Token里面服务端无状态接口层做了鉴权之后剩下的就是把验签密钥配置好。多台机器只要密钥一致都能验证同一个Token。这就让认证这块从“会话存储问题”简化成了“加密验签问题”逻辑上干净得多。1.2 JWT适合什么项目不适合什么项目每个技术选型都有它的边界。JWT比较适合纯API接口服务尤其是前后端分离的项目。登录状态需要被多个客户端浏览器、小程序、App共享的场景。希望认证逻辑简单、服务端无状态、便于横向扩容的系统。但不适合的场景也有不少服务端需要主动踢人下线的场景比如后台管理系统要封禁某个用户JWT在过期之前会一直有效除非你引入黑名单机制。对Token实时失效要求极高的场景JWT的“无状态”反而是缺点要兼容“主动失效”就得额外维护状态绕来绕去又回到了起点。同一个浏览器多标签切换、频繁刷新时可能遇到Token过期的体验问题也需要前端做额外处理。我当时接手这个项目的时候需求很明确一套Web API给前端和后端管理系统共用认证方式要简单可靠还要支持后续多实例部署。JWT几乎是唯一不用绕路的选择。如果你的业务不是上面那几种特例用JWT基本不会错。2. JWT的结构拆解三段式到底存了什么JWT全称是JSON Web Token它不是一个“加密”后的内容而是一个经过Base64编码再加签名的字符串。这点必须从一开始就搞清楚——Token里能看到的信息都是明文的任何人拿到Token都可以用Base64解码看到里面的内容。所以千万不要把密码、身份证号这类敏感数据直接塞到Token里。JWT的“安全”靠的是签名防止篡改不是靠加密防偷看。一个标准的JWT由三部分组成用点号隔开长这样eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZXhwIjoxNjI2OTM1MjAwfQ.8gGxUgfiL9JcP3a7HmJZnlBx5Q0qV6dGtZvsjyc3Ws2.1 Header和Payload的作用第一部分是Header里面记录了签名算法和Token类型。最常见的组合是{alg:HS256,typ:JWT}表示用HMAC-SHA256做签名类型是JWT。第二部分是Payload也就是承载的数据部分里面放的是你声明的Claims。通常包括sub主题一般放用户唯一ID。name用户名或显示名。role角色信息。iatToken签发时间。expToken过期时间。这里要注意一个细节在.Net Core 2.1的JwtSecurityTokenHandler中如果你使用JwtRegisteredClaimNames.Sub这类系统定义的Claim名称它在序列化和反序列化时可能会被自动映射成XML Schema风格的长名称比如http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier。这会导致你后面从HttpContext.User里按sub去查时取不到值。我之前在这个问题上卡了一段时间后面细讲。2.2 签名是怎么算出来的第三部分Signature就是签名它的计算过程是把Base64URL编码后的Header和Payload用点号拼接。使用约定的密钥比如一串自定义的secret字符串作为钥匙。使用Header中声明的算法对拼接结果做HMAC-SHA256运算。把运算后的二进制结果再做一次Base64URL编码。服务端每次收到Token后用同样的密钥和同样的算法自己重新算一遍签名然后和Token自带的签名比对。只要有一点不同就说明Token被篡改过或者密钥不对直接拒绝。这个机制保证了Token的完整性但不保证数据的保密性。因此敏感信息要慎重放入Claims密钥也绝不能硬编码在代码里。2.3 前端存储Token的三种方式Token生成之后要交给前端保存前端在每次请求时把它放进请求头的Authorization字段格式是Bearer token。前端存储方式主要有三种各有取舍localStorage最简单但存在XSS攻击下被读取的风险。适合内部系统、或者前端团队对XSS防护有把握的场景。sessionStorage关闭浏览器Tab就失效适合比较短的会话场景但用户刷新后又要重新登录。CookieHttpOnly相对安全因为脚本拿不到Cookie可以有效避免XSS读取但你需要处理CSRF的问题而且这种方式又回到了“类似Session”的模式跨域调用时还要精细配置Cookie策略。我个人的习惯是中大型系统优先CookieHttpOnly小规模内部工具用localStorage也能接受。但不管哪种方式Token都应该设置合理的过期时间而不是一劳永逸。3. 实战接入从生成Token到中间件验签接下来是真正的动手环节。目标很明确做一个登录接口用户用用户名密码换Token然后受保护的接口必须带着Token才能访问。整个流程就两大块签发Token的代码和验证Token的中间件配置。下面所有代码我都是在.Net Core 2.1环境下验证跑通的。3.1 安装依赖包首先在项目里引入官方JWT认证扩展包。在NuGet控制台里执行Install-Package Microsoft.AspNetCore.Authentication.JwtBearer -Version 2.1.2选2.1.2这个版本是为了匹配.Net Core 2.1的运行时避免高版本包依赖更高版本的框架。版本不对的话会出现各种奇怪的编译错误所以这里别顺手装最新版。3.2 封装一个Token生成器创建一个JwtHelper类集中管理Token的生成逻辑。这么做的好处是以后改密钥、改过期时间、加Claims都只需要动这一个文件。using System; using System.Collections.Generic; using System.IdentityModel.Tokens.Jwt; using System.Security.Claims; using System.Text; using Microsoft.IdentityModel.Tokens; public class JwtHelper { private readonly string _secret; private readonly string _issuer; private readonly string _audience; public JwtHelper(string secret, string issuer, string audience) { _secret secret; _issuer issuer; _audience audience; } public string CreateToken(int userId, string userName, string role, int expireMinutes 120) { var claims new ListClaim { new Claim(ClaimTypes.NameIdentifier, userId.ToString()), new Claim(ClaimTypes.Name, userName), new Claim(ClaimTypes.Role, role), new Claim(jti, Guid.NewGuid().ToString()) }; var key new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_secret)); var credentials new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var token new JwtSecurityToken( issuer: _issuer, audience: _audience, claims: claims, notBefore: DateTime.Now, expires: DateTime.Now.AddMinutes(expireMinutes), signingCredentials: credentials ); return new JwtSecurityTokenHandler().WriteToken(token); } }这里我用了ClaimTypes.NameIdentifier、ClaimTypes.Name、ClaimTypes.Role这些标准Claim类型而不是直接用sub、name、role的缩写。原因是.Net Core的ClaimsPrincipal在解析Token时会把JWT里的短名称映射到这些标准长名称上你写ClaimTypes.NameIdentifier后面读取时直接用User.FindFirst(ClaimTypes.NameIdentifier)就能拿到值不容易踩坑。需要注意的是new JwtSecurityTokenHandler().WriteToken(token)在部分场景下会触发一个警告提示用JwtSecurityTokenHandler的线程安全单例模式更好但2.1环境下直接new一次问题不大因为调用频率不算高。如果你追求严谨也可以把Handler提出来做成静态字段。3.3 在Startup里配置鉴权中间件接下来是核心配置。打开Startup.cs在ConfigureServices方法里添加认证服务public void ConfigureServices(IServiceCollection services) { // 其他服务配置 services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { var secret Configuration[Jwt:Secret]; var issuer Configuration[Jwt:Issuer]; var audience Configuration[Jwt:Audience]; options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidIssuer issuer, ValidateAudience true, ValidAudience audience, ValidateIssuerSigningKey true, IssuerSigningKey new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secret)), ValidateLifetime true, ClockSkew TimeSpan.FromSeconds(30) }; }); services.AddMvc(); }然后在Configure方法里必须在UseMvc之前加上UseAuthenticationpublic void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseAuthentication(); app.UseMvc(); }UseAuthentication这行是很多新手漏掉的重灾区。少了它鉴权中间件根本不会执行接口上的[Authorize]特性形同虚设而且也不会报错你会看到所有请求都能直接访问。这种“静默失效”的问题排查起来非常费劲。3.4 密钥为什么不能硬编码上面的配置里密钥我是从Configuration[Jwt:Secret]读取的这就意味着密钥应该放在appsettings.json里或者更进一步放在环境变量、配置中心里。最简单的做法是在appsettings.json中添加{ Jwt: { Secret: 请替换成至少32位的随机字符串, Issuer: YourProjectName, Audience: YourProjectClient } }密钥的长度和随机性直接决定了HS256签名的强度。建议至少32个字符用大小写字母数字特殊符号混排。我之前见过有人把密钥设成123456这种等于把门锁拆了。生产环境里还可以考虑用环境变量覆盖appsettings这样代码仓库里不保留真实密钥安全性会好很多。还有一点JWT的密钥和加密密码不是一个概念它不需要可读性只需要随机、长度足够、不会被猜到。如果有条件建议定期轮换轮换时需要保证新旧密钥在过渡期内都能通过验签否则正在使用的用户会被突然踢下线。3.5 登录接口与受保护接口的完整范例现在写一个最典型的Controller例子。假设有个AccountController负责登录有个UserController负责返回用户资料。[Route(api/[controller])] [ApiController] public class AccountController : ControllerBase { private readonly JwtHelper _jwtHelper; public AccountController(JwtHelper jwtHelper) { _jwtHelper jwtHelper; } [HttpPost(login)] [AllowAnonymous] public IActionResult Login([FromBody] LoginRequest request) { // 这里省略真实的用户名密码校验逻辑 // 实际项目中应该查库、比对密码哈希不能用明文 if (request.UserName admin request.Password 123456) { var token _jwtHelper.CreateToken(1001, admin, Admin); return Ok(new { token, expires DateTime.Now.AddMinutes(120) }); } return Unauthorized(new { message 用户名或密码错误 }); } }注意[AllowAnonymous]特性它表示这个接口不需要Token就能访问。登录接口肯定要加这个否则就变成鸡生蛋的问题了。然后是受保护接口[Route(api/[controller])] [ApiController] public class UserController : ControllerBase { [HttpGet(profile)] [Authorize] public IActionResult GetProfile() { var userId User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var userName User.FindFirst(ClaimTypes.Name)?.Value; var role User.FindFirst(ClaimTypes.Role)?.Value; return Ok(new { userId, userName, role }); } }[Authorize]特性标记的接口请求时必须带有合法的Token否则中间件直接返回401。这就是整套认证闭环。关于登录接口还有一点要提醒永远不要用明文密码比对生产环境必须用哈希算法存储和校验密码。JWT只负责“你登录过之后怎么识别你”至于“密码是否安全”是另一码事两件事都不要松懈。4. 实操中高频问题与排查思路代码跑通只是第一步真正让人头疼的是那些光看文档根本发现不了的细节问题。我在做这个项目时光是调通整个链路就踩了四五个坑。下面把这些高频问题整理出来每一条都附上原因分析和排查方向。4.1 一直401最常见的三层原因如果你配置看起来都对但请求时始终返回401优先检查三个点是否在Configure里加了app.UseAuthentication()。漏掉这句[Authorize]不会被触发但也可能表现为“永远通过”而不是401取决于你的配置。TokenValidationParameters的ValidIssuer、ValidAudience和IssuerSigningKey是否与生成Token时一致。有一个对不上验签直接失败。前端请求头是否真的带了Authorization: Bearer token。有时候前端把Token放在自定义Header里比如X-Token这是不行的。JWT中间件默认只从Authorization头读取。我用过的最快排查方式先用Postman手动试一次把Token手动复制到请求头里如果Postman能通而页面不通那问题一定在前端请求封装那一层。4.2 Claims取不到值名称映射的坑这是.Net Core里非常容易踩的坑。你在生成Token时明明写了一个ClaimTypes.Name但接口里用User.FindFirst(ClaimTypes.Name)却查不到。原因在于JwtSecurityTokenHandler在解析Token时默认开启了InboundClaimTypeMap映射机制。微软把JWT里那些标准的短名称比如sub映射成了.NET自己的长名称有些映射还会造成重复。比如你生成Token时用了ClaimTypes.Name它的底层URI是http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name而这个URI本身就有映射解析后ClaimType可能变成别的长字符串。解决方法有三个生成Token和读取Claims都使用JwtRegisteredClaimNames.Sub这种短名称并在读取时用短名称去取。在AddJwtBearer的配置里把options.MapInboundClaims false关闭自动映射这样解析出来的ClaimType就会保持原样。统一用自定义的Claim名称比如new Claim(uid, userId.ToString())读取时User.FindFirst(uid)。这种方式最直观也不容易受映射机制影响。我当时为了实现登录用户名和角色能直接读取选择了自定义名称的方案绕开了映射问题。你如果代码已经跑起来了建议优先用自定义名称维护成本最低。4.3 ClockSkew为什么Token刚过期还能用JWT中间件有个默认配置叫ClockSkew默认值是5分钟。意思是就算Token的过期时间已经过了中间件还会额外容忍5分钟的偏差防止服务器和客户端时钟不一致导致正常用户突然被踢下线。也就是说你设置了Token有效期2小时用户实际可以用2小时05分钟。这在大多数业务场景下是没问题的但如果你的业务对过期时间要求非常严格比如金融类操作、临时授权链接可以把ClockSkew调小options.TokenValidationParameters.ClockSkew TimeSpan.FromSeconds(30);如果完全不希望有宽限可以设成TimeSpan.Zero。这个属性很容易被忽略但如果你发现Token过期了还能访问接口先看看是不是它。4.4 过期Token的处理策略Token过期是必然的。前端在请求时如果收到401通常有两种处理策略一是前端拦截401响应自动跳转到登录页让用户重新登录。这是最简单粗暴的方案适合普通后台管理系统。二是引入刷新Token机制登录时给两个Token一个短期AccessToken比如2小时一个长期RefreshToken比如7天。AccessToken过期后前端用RefreshToken去换新的AccessToken用户无感知地续期。这个方案体验好但复杂度也明显增加——RefreshToken需要在服务端存储因为它可以被撤销、必须保证一次有效。如果你是第一次在这个项目里做JWT我建议先做第一种把基础链路跑通。刷新Token是后续优化的事不要一开始就背上复杂度。4.5 跨域请求下的Bearer传递问题前后端分离的项目基本都离不开跨域配置。在.Net Core 2.1里你需要手动启用CORSpublic void ConfigureServices(IServiceCollection services) { services.AddCors(options { options.AddPolicy(AllowAll, policy policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader()); }); } public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseCors(AllowAll); app.UseAuthentication(); app.UseMvc(); }有几个细节需要注意UseCors和UseAuthentication的顺序实际上CORS的处理和认证先后关系不大但必须确保CORS中间件配在UseMvc之前。如果你的前端启用了credentials: include去携带Cookie那么AllowAnyOrigin()就不够用了必须换成WithOrigins(具体的前端地址)并加上.AllowCredentials()。这是浏览器安全策略的限制。自定义请求头的名称如果在CORS策略里没有被允许会触发预检请求失败。如果你改用了自定义Token头这里要显式Allow这个Header。4.6 “用户名或密码错误”到底该返回什么状态码一个容易被忽略的小细节登录失败时很多人习惯返回400或200加一个错误码字段但我建议返回401语义上最准确。前端可以根据状态码决定是弹出“用户名或密码错误”还是直接跳转登录页逻辑上更清晰。当然也要注意生产环境的安全习惯。不管用户不存在还是密码错误返回的提示文案最好统一为“用户名或密码错误”避免通过不同的提示信息猜测出有效用户名。5. 后续扩展与安全加固基础JWT认证做完项目能跑起来了但距离“可靠”还有一段距离。下面这几个点是生产环境里大概率会遇到的问题提前处理能省很多事。5.1 给Token加角色限制[Authorize]不止能判断“是否登录”还能判断“是否有权限”。比如你希望只有Admin角色才能删除数据可以这样写[HttpDelete({id})] [Authorize(Roles Admin)] public IActionResult Delete(int id) { // 只有Admin角色才能走到这里 }多个角色用逗号分隔[Authorize(Roles Admin,Editor)]。角色Claim在生成Token时就必须带上中间件会把它解析到User.IsInRole(Admin)的判断中。需要注意如果你关闭了Claim映射MapInboundClaimsfalse角色判断可能受影响因为IsInRole默认查的是ClaimTypes.Role的映射值。这种情况下建议保留默认映射或者使用自定义策略。在没踩过坑之前建议先按默认配置来。5.2 让Token“短命”是JWT安全的第一原则JWT无状态的特点意味着服务端没法主动让Token失效。所以在安全策略上Token的过期时间一定要短。我建议普通内部后台系统2小时比较合适。面向用户的App接口可以适当延长到12-24小时。涉及金额、权限变更的操作Token生命周期越短越好配合刷新机制使用。如果你担心用户频繁登录体验太差可以通过刷新Token机制来平衡安全性和体验。还有一个小技巧如果某个用户要改密码最好的做法是让客户端立刻清理本地Token并且在服务端维护一个“Token版本号”或“密码修改时间戳”验签时检查Token签发时间是否早于密码修改时间早于就拒绝。5.3 不要让一个密钥打天下很多项目图省事所有环境共用一套JWT密钥。这带来的问题是只要开发环境的密钥泄露生产环境也一起沦陷。正确做法是每个环境开发、测试、生产使用不同密钥由环境变量注入。再进阶一点当你想轮换密钥时需要小心处理。JwtBearer中间件只支持一个TokenValidationParameters但你可以通过自定义IssuerSigningKeyResolver来实现多密钥兼容。在过渡期内旧密钥签发的Token依然有效新密钥签发的Token也能通过等旧Token全部自然过期后再下线旧密钥。这个过程在大型系统里很常见。options.TokenValidationParameters.IssuerSigningKeyResolver (token, securityToken, kid, parameters) { var keys new ListSecurityKey { new SymmetricSecurityKey(Encoding.UTF8.GetBytes(新密钥)), new SymmetricSecurityKey(Encoding.UTF8.GetBytes(旧密钥)) }; return keys; };上面的代码是把新旧密钥都配置进去两个密钥都能通过验签两边同时有效。这在做密钥轮换时是一个很好的过渡方案。5.4 用JwtBearerEvents记录鉴权失败原因当接口返回401的时候服务端日志里往往没有任何记录排查起来很被动。这里可以配置JwtBearerEvents在认证失败时把原因写进日志options.Events new JwtBearerEvents { OnAuthenticationFailed context { // context.Exception 就是认证失败的具体异常 Console.WriteLine($认证失败{context.Exception?.Message}); return Task.CompletedTask; }, OnChallenge context { // 在这里可以自定义401响应的内容 return Task.CompletedTask; } };通过OnAuthenticationFailed拿到Exception你会很直观地看到是签名不匹配、过期了还是Issuer/Audience校验失败。这个能力在联调阶段尤其有用。5.5 统一返回格式而不是直接裸返回401默认情况下[Authorize]拦截后返回的401是空体前端拿到一个没有任何信息的响应体验很差。通过OnChallenge事件你可以统一返回JSON格式OnChallenge async context { context.HandleResponse(); context.Response.StatusCode 401; context.Response.ContentType application/json; await context.Response.WriteAsync(JsonConvert.SerializeObject(new { code 401, message 未授权或Token已过期 })); }这样做的好处是前后端约定了一套统一的错误响应结构前端只需要处理code401这一类情况不用针对不同平台解析不同错误格式。写在最后JWT这套东西在.Net Core 2.1里实现起来并不复杂核心就是“一个签发方法 一段中间件配置”难的是那些藏在细节里的坑中间件顺序、Claims映射、时钟偏差、密钥管理、跨域传递。我在实际项目中踩过不少回最深刻的体会就是——先把“生成→传递→验签→取Claims”这条链路完整跑通再去做权限细化、刷新Token这些扩展否则一旦出问题你根本分不清是哪个环节挂了。老项目虽然技术栈旧但业务价值还在。如果你也是在维护.Net Core 2.1的老系统希望这篇文章能帮你把这套认证机制彻底搞清楚。下次遇到401不要慌按照上面列的几个排查点逐项确认基本都能找到答案。
算年头.Net Core 2.1都已经是微软官方停止支持的老框架了但我发现直到今天还有不少老项目在它上面跑着而且最典型的需求之一就是“用JWT生成Token做身份认证”。不夸张地说JWT已经成了前后端分离架构下做认证的事实标准。这篇文章我不打算贴一大堆官方文档而是从一个做过的真实项目角度出发把这套东西从原理到落地再到排查问题完整拆开揉碎讲一遍。如果你正在维护一个.Net Core 2.1的老项目或者刚接手这样的代码又或者只是想搞明白JWT在服务端到底是怎么“验”的这篇文章都适合你。我会把Token生成、中间件配置、Claims设计、常见401/403问题一次讲清楚很多细节是官方文档里不会写的。1. 为什么要用JWT而不是Session很多从.Net Framework时代转过来的同学第一时间想的是以前用Session不也挺好的确实传统的Session认证方式在小规模单体应用里完全够用但它存在一个比较麻烦的先天问题——Session存储在服务器内存里客户端只保存一个SessionId。用户量一旦上来或者你需要横向扩容部署多台服务器Session就变成了一个坑这台机器登录的另一台机器不认识得专门去做Session共享比如用Redis存Session。这些工作能跑通但复杂度明显上去了。JWT的思路完全不同用户登录成功后服务器算出一个经过签名的Token把它直接返回给客户端。客户端之后的每一次请求在请求头里带上这个Token服务器只要验签通过就放行。服务器本身不存Token所以也就没有“分布式Session同步”这种烦恼。这种无状态的设计对于构建Web API、小程序后台、App接口尤其是前后端完全分离的项目非常友好。1.1 无状态认证为什么更适合现在的架构现在的项目很少是一个单体MVC走天下前端一个Vue或React应用后端一个Web API甚至后端还有好几个服务。这种情况下如果用Session会出现几个让人头疼的问题多端登录状态难以统一管理Web端、小程序、App各有一套SessionId处理起来很分裂。Session默认依赖Cookie传递但App或小程序里对Cookie的支持并不像浏览器那样“开箱即用”。服务端扩展时会话数据同步总是绕不开的额外工作。JWT把用户身份信息直接编码在Token里面服务端无状态接口层做了鉴权之后剩下的就是把验签密钥配置好。多台机器只要密钥一致都能验证同一个Token。这就让认证这块从“会话存储问题”简化成了“加密验签问题”逻辑上干净得多。1.2 JWT适合什么项目不适合什么项目每个技术选型都有它的边界。JWT比较适合纯API接口服务尤其是前后端分离的项目。登录状态需要被多个客户端浏览器、小程序、App共享的场景。希望认证逻辑简单、服务端无状态、便于横向扩容的系统。但不适合的场景也有不少服务端需要主动踢人下线的场景比如后台管理系统要封禁某个用户JWT在过期之前会一直有效除非你引入黑名单机制。对Token实时失效要求极高的场景JWT的“无状态”反而是缺点要兼容“主动失效”就得额外维护状态绕来绕去又回到了起点。同一个浏览器多标签切换、频繁刷新时可能遇到Token过期的体验问题也需要前端做额外处理。我当时接手这个项目的时候需求很明确一套Web API给前端和后端管理系统共用认证方式要简单可靠还要支持后续多实例部署。JWT几乎是唯一不用绕路的选择。如果你的业务不是上面那几种特例用JWT基本不会错。2. JWT的结构拆解三段式到底存了什么JWT全称是JSON Web Token它不是一个“加密”后的内容而是一个经过Base64编码再加签名的字符串。这点必须从一开始就搞清楚——Token里能看到的信息都是明文的任何人拿到Token都可以用Base64解码看到里面的内容。所以千万不要把密码、身份证号这类敏感数据直接塞到Token里。JWT的“安全”靠的是签名防止篡改不是靠加密防偷看。一个标准的JWT由三部分组成用点号隔开长这样eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZXhwIjoxNjI2OTM1MjAwfQ.8gGxUgfiL9JcP3a7HmJZnlBx5Q0qV6dGtZvsjyc3Ws2.1 Header和Payload的作用第一部分是Header里面记录了签名算法和Token类型。最常见的组合是{alg:HS256,typ:JWT}表示用HMAC-SHA256做签名类型是JWT。第二部分是Payload也就是承载的数据部分里面放的是你声明的Claims。通常包括sub主题一般放用户唯一ID。name用户名或显示名。role角色信息。iatToken签发时间。expToken过期时间。这里要注意一个细节在.Net Core 2.1的JwtSecurityTokenHandler中如果你使用JwtRegisteredClaimNames.Sub这类系统定义的Claim名称它在序列化和反序列化时可能会被自动映射成XML Schema风格的长名称比如http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier。这会导致你后面从HttpContext.User里按sub去查时取不到值。我之前在这个问题上卡了一段时间后面细讲。2.2 签名是怎么算出来的第三部分Signature就是签名它的计算过程是把Base64URL编码后的Header和Payload用点号拼接。使用约定的密钥比如一串自定义的secret字符串作为钥匙。使用Header中声明的算法对拼接结果做HMAC-SHA256运算。把运算后的二进制结果再做一次Base64URL编码。服务端每次收到Token后用同样的密钥和同样的算法自己重新算一遍签名然后和Token自带的签名比对。只要有一点不同就说明Token被篡改过或者密钥不对直接拒绝。这个机制保证了Token的完整性但不保证数据的保密性。因此敏感信息要慎重放入Claims密钥也绝不能硬编码在代码里。2.3 前端存储Token的三种方式Token生成之后要交给前端保存前端在每次请求时把它放进请求头的Authorization字段格式是Bearer token。前端存储方式主要有三种各有取舍localStorage最简单但存在XSS攻击下被读取的风险。适合内部系统、或者前端团队对XSS防护有把握的场景。sessionStorage关闭浏览器Tab就失效适合比较短的会话场景但用户刷新后又要重新登录。CookieHttpOnly相对安全因为脚本拿不到Cookie可以有效避免XSS读取但你需要处理CSRF的问题而且这种方式又回到了“类似Session”的模式跨域调用时还要精细配置Cookie策略。我个人的习惯是中大型系统优先CookieHttpOnly小规模内部工具用localStorage也能接受。但不管哪种方式Token都应该设置合理的过期时间而不是一劳永逸。3. 实战接入从生成Token到中间件验签接下来是真正的动手环节。目标很明确做一个登录接口用户用用户名密码换Token然后受保护的接口必须带着Token才能访问。整个流程就两大块签发Token的代码和验证Token的中间件配置。下面所有代码我都是在.Net Core 2.1环境下验证跑通的。3.1 安装依赖包首先在项目里引入官方JWT认证扩展包。在NuGet控制台里执行Install-Package Microsoft.AspNetCore.Authentication.JwtBearer -Version 2.1.2选2.1.2这个版本是为了匹配.Net Core 2.1的运行时避免高版本包依赖更高版本的框架。版本不对的话会出现各种奇怪的编译错误所以这里别顺手装最新版。3.2 封装一个Token生成器创建一个JwtHelper类集中管理Token的生成逻辑。这么做的好处是以后改密钥、改过期时间、加Claims都只需要动这一个文件。using System; using System.Collections.Generic; using System.IdentityModel.Tokens.Jwt; using System.Security.Claims; using System.Text; using Microsoft.IdentityModel.Tokens; public class JwtHelper { private readonly string _secret; private readonly string _issuer; private readonly string _audience; public JwtHelper(string secret, string issuer, string audience) { _secret secret; _issuer issuer; _audience audience; } public string CreateToken(int userId, string userName, string role, int expireMinutes 120) { var claims new ListClaim { new Claim(ClaimTypes.NameIdentifier, userId.ToString()), new Claim(ClaimTypes.Name, userName), new Claim(ClaimTypes.Role, role), new Claim(jti, Guid.NewGuid().ToString()) }; var key new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_secret)); var credentials new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var token new JwtSecurityToken( issuer: _issuer, audience: _audience, claims: claims, notBefore: DateTime.Now, expires: DateTime.Now.AddMinutes(expireMinutes), signingCredentials: credentials ); return new JwtSecurityTokenHandler().WriteToken(token); } }这里我用了ClaimTypes.NameIdentifier、ClaimTypes.Name、ClaimTypes.Role这些标准Claim类型而不是直接用sub、name、role的缩写。原因是.Net Core的ClaimsPrincipal在解析Token时会把JWT里的短名称映射到这些标准长名称上你写ClaimTypes.NameIdentifier后面读取时直接用User.FindFirst(ClaimTypes.NameIdentifier)就能拿到值不容易踩坑。需要注意的是new JwtSecurityTokenHandler().WriteToken(token)在部分场景下会触发一个警告提示用JwtSecurityTokenHandler的线程安全单例模式更好但2.1环境下直接new一次问题不大因为调用频率不算高。如果你追求严谨也可以把Handler提出来做成静态字段。3.3 在Startup里配置鉴权中间件接下来是核心配置。打开Startup.cs在ConfigureServices方法里添加认证服务public void ConfigureServices(IServiceCollection services) { // 其他服务配置 services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { var secret Configuration[Jwt:Secret]; var issuer Configuration[Jwt:Issuer]; var audience Configuration[Jwt:Audience]; options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidIssuer issuer, ValidateAudience true, ValidAudience audience, ValidateIssuerSigningKey true, IssuerSigningKey new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secret)), ValidateLifetime true, ClockSkew TimeSpan.FromSeconds(30) }; }); services.AddMvc(); }然后在Configure方法里必须在UseMvc之前加上UseAuthenticationpublic void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseAuthentication(); app.UseMvc(); }UseAuthentication这行是很多新手漏掉的重灾区。少了它鉴权中间件根本不会执行接口上的[Authorize]特性形同虚设而且也不会报错你会看到所有请求都能直接访问。这种“静默失效”的问题排查起来非常费劲。3.4 密钥为什么不能硬编码上面的配置里密钥我是从Configuration[Jwt:Secret]读取的这就意味着密钥应该放在appsettings.json里或者更进一步放在环境变量、配置中心里。最简单的做法是在appsettings.json中添加{ Jwt: { Secret: 请替换成至少32位的随机字符串, Issuer: YourProjectName, Audience: YourProjectClient } }密钥的长度和随机性直接决定了HS256签名的强度。建议至少32个字符用大小写字母数字特殊符号混排。我之前见过有人把密钥设成123456这种等于把门锁拆了。生产环境里还可以考虑用环境变量覆盖appsettings这样代码仓库里不保留真实密钥安全性会好很多。还有一点JWT的密钥和加密密码不是一个概念它不需要可读性只需要随机、长度足够、不会被猜到。如果有条件建议定期轮换轮换时需要保证新旧密钥在过渡期内都能通过验签否则正在使用的用户会被突然踢下线。3.5 登录接口与受保护接口的完整范例现在写一个最典型的Controller例子。假设有个AccountController负责登录有个UserController负责返回用户资料。[Route(api/[controller])] [ApiController] public class AccountController : ControllerBase { private readonly JwtHelper _jwtHelper; public AccountController(JwtHelper jwtHelper) { _jwtHelper jwtHelper; } [HttpPost(login)] [AllowAnonymous] public IActionResult Login([FromBody] LoginRequest request) { // 这里省略真实的用户名密码校验逻辑 // 实际项目中应该查库、比对密码哈希不能用明文 if (request.UserName admin request.Password 123456) { var token _jwtHelper.CreateToken(1001, admin, Admin); return Ok(new { token, expires DateTime.Now.AddMinutes(120) }); } return Unauthorized(new { message 用户名或密码错误 }); } }注意[AllowAnonymous]特性它表示这个接口不需要Token就能访问。登录接口肯定要加这个否则就变成鸡生蛋的问题了。然后是受保护接口[Route(api/[controller])] [ApiController] public class UserController : ControllerBase { [HttpGet(profile)] [Authorize] public IActionResult GetProfile() { var userId User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var userName User.FindFirst(ClaimTypes.Name)?.Value; var role User.FindFirst(ClaimTypes.Role)?.Value; return Ok(new { userId, userName, role }); } }[Authorize]特性标记的接口请求时必须带有合法的Token否则中间件直接返回401。这就是整套认证闭环。关于登录接口还有一点要提醒永远不要用明文密码比对生产环境必须用哈希算法存储和校验密码。JWT只负责“你登录过之后怎么识别你”至于“密码是否安全”是另一码事两件事都不要松懈。4. 实操中高频问题与排查思路代码跑通只是第一步真正让人头疼的是那些光看文档根本发现不了的细节问题。我在做这个项目时光是调通整个链路就踩了四五个坑。下面把这些高频问题整理出来每一条都附上原因分析和排查方向。4.1 一直401最常见的三层原因如果你配置看起来都对但请求时始终返回401优先检查三个点是否在Configure里加了app.UseAuthentication()。漏掉这句[Authorize]不会被触发但也可能表现为“永远通过”而不是401取决于你的配置。TokenValidationParameters的ValidIssuer、ValidAudience和IssuerSigningKey是否与生成Token时一致。有一个对不上验签直接失败。前端请求头是否真的带了Authorization: Bearer token。有时候前端把Token放在自定义Header里比如X-Token这是不行的。JWT中间件默认只从Authorization头读取。我用过的最快排查方式先用Postman手动试一次把Token手动复制到请求头里如果Postman能通而页面不通那问题一定在前端请求封装那一层。4.2 Claims取不到值名称映射的坑这是.Net Core里非常容易踩的坑。你在生成Token时明明写了一个ClaimTypes.Name但接口里用User.FindFirst(ClaimTypes.Name)却查不到。原因在于JwtSecurityTokenHandler在解析Token时默认开启了InboundClaimTypeMap映射机制。微软把JWT里那些标准的短名称比如sub映射成了.NET自己的长名称有些映射还会造成重复。比如你生成Token时用了ClaimTypes.Name它的底层URI是http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name而这个URI本身就有映射解析后ClaimType可能变成别的长字符串。解决方法有三个生成Token和读取Claims都使用JwtRegisteredClaimNames.Sub这种短名称并在读取时用短名称去取。在AddJwtBearer的配置里把options.MapInboundClaims false关闭自动映射这样解析出来的ClaimType就会保持原样。统一用自定义的Claim名称比如new Claim(uid, userId.ToString())读取时User.FindFirst(uid)。这种方式最直观也不容易受映射机制影响。我当时为了实现登录用户名和角色能直接读取选择了自定义名称的方案绕开了映射问题。你如果代码已经跑起来了建议优先用自定义名称维护成本最低。4.3 ClockSkew为什么Token刚过期还能用JWT中间件有个默认配置叫ClockSkew默认值是5分钟。意思是就算Token的过期时间已经过了中间件还会额外容忍5分钟的偏差防止服务器和客户端时钟不一致导致正常用户突然被踢下线。也就是说你设置了Token有效期2小时用户实际可以用2小时05分钟。这在大多数业务场景下是没问题的但如果你的业务对过期时间要求非常严格比如金融类操作、临时授权链接可以把ClockSkew调小options.TokenValidationParameters.ClockSkew TimeSpan.FromSeconds(30);如果完全不希望有宽限可以设成TimeSpan.Zero。这个属性很容易被忽略但如果你发现Token过期了还能访问接口先看看是不是它。4.4 过期Token的处理策略Token过期是必然的。前端在请求时如果收到401通常有两种处理策略一是前端拦截401响应自动跳转到登录页让用户重新登录。这是最简单粗暴的方案适合普通后台管理系统。二是引入刷新Token机制登录时给两个Token一个短期AccessToken比如2小时一个长期RefreshToken比如7天。AccessToken过期后前端用RefreshToken去换新的AccessToken用户无感知地续期。这个方案体验好但复杂度也明显增加——RefreshToken需要在服务端存储因为它可以被撤销、必须保证一次有效。如果你是第一次在这个项目里做JWT我建议先做第一种把基础链路跑通。刷新Token是后续优化的事不要一开始就背上复杂度。4.5 跨域请求下的Bearer传递问题前后端分离的项目基本都离不开跨域配置。在.Net Core 2.1里你需要手动启用CORSpublic void ConfigureServices(IServiceCollection services) { services.AddCors(options { options.AddPolicy(AllowAll, policy policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader()); }); } public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseCors(AllowAll); app.UseAuthentication(); app.UseMvc(); }有几个细节需要注意UseCors和UseAuthentication的顺序实际上CORS的处理和认证先后关系不大但必须确保CORS中间件配在UseMvc之前。如果你的前端启用了credentials: include去携带Cookie那么AllowAnyOrigin()就不够用了必须换成WithOrigins(具体的前端地址)并加上.AllowCredentials()。这是浏览器安全策略的限制。自定义请求头的名称如果在CORS策略里没有被允许会触发预检请求失败。如果你改用了自定义Token头这里要显式Allow这个Header。4.6 “用户名或密码错误”到底该返回什么状态码一个容易被忽略的小细节登录失败时很多人习惯返回400或200加一个错误码字段但我建议返回401语义上最准确。前端可以根据状态码决定是弹出“用户名或密码错误”还是直接跳转登录页逻辑上更清晰。当然也要注意生产环境的安全习惯。不管用户不存在还是密码错误返回的提示文案最好统一为“用户名或密码错误”避免通过不同的提示信息猜测出有效用户名。5. 后续扩展与安全加固基础JWT认证做完项目能跑起来了但距离“可靠”还有一段距离。下面这几个点是生产环境里大概率会遇到的问题提前处理能省很多事。5.1 给Token加角色限制[Authorize]不止能判断“是否登录”还能判断“是否有权限”。比如你希望只有Admin角色才能删除数据可以这样写[HttpDelete({id})] [Authorize(Roles Admin)] public IActionResult Delete(int id) { // 只有Admin角色才能走到这里 }多个角色用逗号分隔[Authorize(Roles Admin,Editor)]。角色Claim在生成Token时就必须带上中间件会把它解析到User.IsInRole(Admin)的判断中。需要注意如果你关闭了Claim映射MapInboundClaimsfalse角色判断可能受影响因为IsInRole默认查的是ClaimTypes.Role的映射值。这种情况下建议保留默认映射或者使用自定义策略。在没踩过坑之前建议先按默认配置来。5.2 让Token“短命”是JWT安全的第一原则JWT无状态的特点意味着服务端没法主动让Token失效。所以在安全策略上Token的过期时间一定要短。我建议普通内部后台系统2小时比较合适。面向用户的App接口可以适当延长到12-24小时。涉及金额、权限变更的操作Token生命周期越短越好配合刷新机制使用。如果你担心用户频繁登录体验太差可以通过刷新Token机制来平衡安全性和体验。还有一个小技巧如果某个用户要改密码最好的做法是让客户端立刻清理本地Token并且在服务端维护一个“Token版本号”或“密码修改时间戳”验签时检查Token签发时间是否早于密码修改时间早于就拒绝。5.3 不要让一个密钥打天下很多项目图省事所有环境共用一套JWT密钥。这带来的问题是只要开发环境的密钥泄露生产环境也一起沦陷。正确做法是每个环境开发、测试、生产使用不同密钥由环境变量注入。再进阶一点当你想轮换密钥时需要小心处理。JwtBearer中间件只支持一个TokenValidationParameters但你可以通过自定义IssuerSigningKeyResolver来实现多密钥兼容。在过渡期内旧密钥签发的Token依然有效新密钥签发的Token也能通过等旧Token全部自然过期后再下线旧密钥。这个过程在大型系统里很常见。options.TokenValidationParameters.IssuerSigningKeyResolver (token, securityToken, kid, parameters) { var keys new ListSecurityKey { new SymmetricSecurityKey(Encoding.UTF8.GetBytes(新密钥)), new SymmetricSecurityKey(Encoding.UTF8.GetBytes(旧密钥)) }; return keys; };上面的代码是把新旧密钥都配置进去两个密钥都能通过验签两边同时有效。这在做密钥轮换时是一个很好的过渡方案。5.4 用JwtBearerEvents记录鉴权失败原因当接口返回401的时候服务端日志里往往没有任何记录排查起来很被动。这里可以配置JwtBearerEvents在认证失败时把原因写进日志options.Events new JwtBearerEvents { OnAuthenticationFailed context { // context.Exception 就是认证失败的具体异常 Console.WriteLine($认证失败{context.Exception?.Message}); return Task.CompletedTask; }, OnChallenge context { // 在这里可以自定义401响应的内容 return Task.CompletedTask; } };通过OnAuthenticationFailed拿到Exception你会很直观地看到是签名不匹配、过期了还是Issuer/Audience校验失败。这个能力在联调阶段尤其有用。5.5 统一返回格式而不是直接裸返回401默认情况下[Authorize]拦截后返回的401是空体前端拿到一个没有任何信息的响应体验很差。通过OnChallenge事件你可以统一返回JSON格式OnChallenge async context { context.HandleResponse(); context.Response.StatusCode 401; context.Response.ContentType application/json; await context.Response.WriteAsync(JsonConvert.SerializeObject(new { code 401, message 未授权或Token已过期 })); }这样做的好处是前后端约定了一套统一的错误响应结构前端只需要处理code401这一类情况不用针对不同平台解析不同错误格式。写在最后JWT这套东西在.Net Core 2.1里实现起来并不复杂核心就是“一个签发方法 一段中间件配置”难的是那些藏在细节里的坑中间件顺序、Claims映射、时钟偏差、密钥管理、跨域传递。我在实际项目中踩过不少回最深刻的体会就是——先把“生成→传递→验签→取Claims”这条链路完整跑通再去做权限细化、刷新Token这些扩展否则一旦出问题你根本分不清是哪个环节挂了。老项目虽然技术栈旧但业务价值还在。如果你也是在维护.Net Core 2.1的老系统希望这篇文章能帮你把这套认证机制彻底搞清楚。下次遇到401不要慌按照上面列的几个排查点逐项确认基本都能找到答案。
)
)
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
