前一阵子接手一个维护了三年多的 .Net Core 2.1 服务第一件要补的事就是给接口加身份认证。和我预期的一样方案绕不开 JWT——生成 Token、验证 Token、把用户身份安全地传递到控制器。JWT 认证在 .Net Core 里已经被封装得比较顺手但 2.1 这个版本处在关键的迭代期网上很多教程讲的是 3.x 甚至 5.x 的写法照抄过来经常在包版本、中间件顺序和 Claim 读取上翻车。这篇文章是完整的落地记录覆盖实现过程、配置参数和各类踩坑点正在维护 2.1 老项目的人可以直接参考新手也能借此建立 JWT 认证的整体概念。1. 为什么在 .Net Core 2.1 时代还是坚持用 JWT 做认证1.1 从 Session 到 Token认证方式变迁的底层逻辑在单机 Web 时代最常见的认证方式是 Session Cookie服务器内存里保存一份会话状态浏览器每次请求自动带上 SessionId服务端拿着 SessionId 查会话数据。这套机制胜在直观但在分布式场景下马上暴露问题请求一旦被负载均衡转发到不同实例会话状态就丢失了。解决办法要么做 Session 持久化要么开启负载均衡粘滞会话但无论哪种都会增加架构复杂度和维护成本。JWT 的思路完全不同。它把“用户是谁、能干什么、什么时候失效”这些信息全部编码进一个自包含的 Token 里服务器不再需要保存任何会话状态。客户端把 Token 保存下来每个请求都带上它服务端拿到后只要验签通过、时效没问题就完全信任这个身份。这种无状态特性让 JWT 在 Web API、前后端分离、微服务架构里成了事实标准。.Net Core 2.1 是跨平台体系中较早的 LTS 版本很多企业内部服务到现在依然在线上运行。给这些老服务补上 JWT 身份认证是大量开发者都会遇到的改造任务。理解它的原理和落地细节不只是对付 2.1 项目对后面升级到新框架也同样有价值。1.2 JWT 令牌的三个构成段与一次完整认证流程JWT 全称 JSON Web Token是一个开放标准RFC 7519。一个 Token 由三段用点分隔的 Base64Url 字符串组成Header、Payload、Signature。Header 声明签名算法比如 HS256和 Token 类型Payload 存放声明信息比如用户 ID、角色、过期时间Signature 是用密钥对前两段内容做的签名确保内容没有被篡改。打个比方Token 就像一张盖了公章的通行证Header 和 Payload 是证件上印的内容Signature 是公章。证件内容谁都能读Base64 只编码不加密但没有对应的章密钥任何人改动内容后都补不上新章。所以 JWT 适合做认证而非保密手机号、密码、身份证这类敏感信息绝不要往 Payload 里塞。一次完整的认证流程围绕下面几个动作展开客户端先调用登录接口提交用户名密码服务端校验通过后用密钥把一堆用户声明打包签成 Token 返回客户端保存 Token后续请求在 Authorization 请求头带上Bearer Token服务端通过认证中间件验证签名、签发者、受众和有效期通过后把用户身份挂到 HttpContext.User 上之后的授权判断和业务代码直接读取即可。这套流程看起来简单但真正落到 .Net Core 2.1 项目里有很多容易栽跟头的工程细节比如 NuGet 包版本、中间件注册顺序、Claim 类型映射、时钟偏移。这些细节散落在官方文档和不同版本的博客里说法还经常互相矛盾整理成完整的过程记录比零散搜索效率高得多。下面从环境准备开始把每一步代码和选择背后的理由讲清楚。2. 项目准备目标框架、NuGet 包与配置项设计2.1 创建项目与确认 .Net Core 2.1 的依赖版本很多人在 2.1 项目里加 JWT 失败第一个坑就是 NuGet 包版本装错。.Net Core 2.1 项目文件里TargetFramework要写成netcoreapp2.1Web API 模板默认引用Microsoft.AspNetCore.App元包但 JWT Bearer 认证中间件并不在元包里需要单独安装dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 2.1.2如果使用 Visual Studio 的包管理器搜索Microsoft.AspNetCore.Authentication.JwtBearer后一定要注意版本选择 2.1.x 系列不要顺手选了 3.x、5.x 甚至更高版本。装错版本的直接后果是程序集冲突编译阶段就是一片红色波浪线而且报错信息晦涩难懂排查起来非常浪费时间。安装完成后项目里会出现两个关键依赖Microsoft.AspNetCore.Authentication.JwtBearer提供认证中间件System.IdentityModel.Tokens.Jwt提供JwtSecurityTokenHandler这个生成和解析 Token 的核心类。如果老项目之前装过System.IdentityModel.Tokens.Jwt的旧版本建议统一升到 5.3.0 以上否则个别签名相关 API 会找不到行为表现也很不稳定。2.2 appsettings.json 里的认证参数怎么设计JWT 认证需要配置的核心参数有四个签发者 Issuer、受众 Audience、签名密钥 SecretKey、Token 有效期 TokenExpireMinutes。把它们单独放进一个配置节方便后续替换和读取{ AuthSettings: { Issuer: MyAuthServer, Audience: MyApiClient, SecretKey: Pssw0rd_Strong_Secret_Key_Replace_Me_2024, TokenExpireMinutes: 30 } }Issuer 表示 Token 由哪个服务签发验证端的 ValidIssuer 必须和生成端完全一致Audience 表示 Token 面向哪个客户端系统前后端分离项目里通常填前端应用名或网关名。这两个参数看似简单作用却很关键它们限定 Token 的使用范围防止某个服务签发的 Token 被另一个毫不相关的服务无条件接受相当于给凭证划定了活动边界。TokenExpireMinutes 直接影响安全性和体验。内部管理后台可以放宽到 60 分钟面向 C 端的接口建议 15 到 30 分钟。时间太长Token 泄露后的风险窗口就大时间太短用户频繁被踢下线口碑也受影响。很多团队后续会引入 Refresh Token 机制平衡这两点但有效期这个参数最好从一开始就做成配置项不要写死在代码里。2.3 密钥的安全生成方法与长度要求密钥是整个 JWT 方案里最敏感的资源。HS256 算法要求密钥字节长度至少 128 位16 个字节否则运行时抛异常常见的错误类型是ArgumentOutOfRangeException提示信息里通常带IDX10708类似编号大意是 SecurityKey 的 KeySize 不能小于 128 位。生成 Token 时报错的人特别多基本都是随手敲了一段很短的字符串当密钥。我一般建议用 32 字节以上的随机串既满足安全强度也避免未来调整算法时长度不够用。生成方式可以这样在 PowerShell 里执行[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }) -as [byte[]])把产出的 Base64 字符串填入配置项注意不要把它提交到 Git 仓库。我的习惯是开发环境放在 appsettings.Development.json生产环境从环境变量或部署平台的密钥管理服务读取比如在读取配置时做一层兜底var secretKey Environment.GetEnvironmentVariable(AUTH_SECRET_KEY) ?? Configuration[AuthSettings:SecretKey];还要强调一点JWT 的 HS256 属于对称签名签发方和验证方共用同一个密钥。如果项目里有多个服务要互相验证 Token密钥的分发、轮换必须提前定好规范不能把明文密钥外传或写在代码注释里否则整个认证体系等于没有防线。3. 核心实现Token 生成、认证注册与中间件接线3.1 登录接口里的 Token 生成逻辑Token 生成的核心是先用用户信息构造一组 Claim声明再用密钥签名。为了代码整洁我先定义一个配置实体类方便依赖注入和测试复用public class AuthSettings { public string Issuer { get; set; } public string Audience { get; set; } public string SecretKey { get; set; } public int TokenExpireMinutes { get; set; } }在登录接口中用户密码校验通过后把用户信息封装成 Claim 数组然后创建并序列化 Tokenprivate string GenerateToken(UserAuthModel user, AuthSettings settings) { var claims new[] { new Claim(ClaimTypes.NameIdentifier, user.UserId.ToString()), new Claim(ClaimTypes.Name, user.UserName), new Claim(ClaimTypes.Role, user.Role), new Claim(department, user.Department), }; var key new SymmetricSecurityKey(Encoding.UTF8.GetBytes(settings.SecretKey)); var credentials new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var now DateTime.UtcNow; var token new JwtSecurityToken( issuer: settings.Issuer, audience: settings.Audience, claims: claims, notBefore: now, expires: now.AddMinutes(settings.TokenExpireMinutes), signingCredentials: credentials); return new JwtSecurityTokenHandler().WriteToken(token); }这里有几个容易被忽略的细节。Claim 相当于是 Token 里声明的字段建议只放认证和授权需要的最小信息比如用户 ID、用户名、角色、部门手机号身份证这类敏感信息绝对不要放进去因为 JWT 的 Payload 只是 Base64 编码任何拿到 Token 的人都能直接解码读出内容。notBefore表示生效时间expires表示过期时间统一用DateTime.UtcNow避免服务器时区差异导致 Token 生效时间错乱。SecurityAlgorithms.HmacSha256是这次使用的对称签名算法也可以换 HmacSha512但 HS256 在各语言平台上的解析库兼容性最好跨服务调用时不建议为了追求强度随意换算法。WriteToken负责把内存里的 Token 对象序列化成最终字符串这个字符串就是客户端要保存并在后续请求中携带的凭证。3.2 Startup.ConfigureServices 里的认证服务注册生成 Token 只完成了一半关键的另一半是让服务端自动验证每个请求携带的 Token。这个能力要在 Startup 的ConfigureServices里注册public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1); var authSettings Configuration.GetSection(AuthSettings).GetAuthSettings(); services.AddSingleton(authSettings); var key new SymmetricSecurityKey(Encoding.UTF8.GetBytes(authSettings.SecretKey)); services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidIssuer authSettings.Issuer, ValidateAudience true, ValidAudience authSettings.Audience, ValidateIssuerSigningKey true, IssuerSigningKey key, ValidateLifetime true, ClockSkew TimeSpan.FromSeconds(30) }; }); }AddAuthentication注册认证框架AddJwtBearer把具体的认证处理器挂上去。TokenValidationParameters是验证参数集合每一行都对应一个独立的校验动作。ValidateIssuer、ValidateAudience、ValidateIssuerSigningKey 这三项建议全部显式打开不要偷懒只留一个签名校验否则将来做安全审计的时候很难交代清楚。ClockSkew很多人不重视。分布式系统里不同服务器时间可能有微小偏差所以认证处理默认允许长达 5 分钟的时钟偏移也就是说 Token 过期后最长 5 分钟内依然可能被接受。默认值对普通业务无所谓但对支付、改密这类敏感接口5 分钟的安全窗口过大了。实际项目里我统一调成 30 秒既不敏感也能扛住正常的时钟抖动。3.3 中间件管道的顺序UseAuthentication 到底该放哪光注册服务还不够还需要在请求管线上启用认证中间件。这一步最容易翻车因为平台不会报错只是所有带 Token 的请求都验证不过。.Net Core 2.1 的 Startup 中Configure方法里正确的顺序是这样public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseAuthentication(); app.UseMvc(); }原则一句话UseAuthentication必须在UseMvc之前。可以这样理解中间件是一串排队执行的关卡Mvc 一旦接管请求后续关卡就没机会执行了。把认证放在 Mvc 前面请求在进入路由和控制器之前Token 就已经被解析好并把用户身份写进 HttpContext.User控制器里的[Authorize]判断身份才有据可依。如果不写UseAuthentication()会出现一个非常迷惑的现象生成 Token 正常、配置文件看着也没问题但访问受保护接口永远 401。原因就是认证中间件根本没有运行HttpContext.User 一直是空的授权过滤器永远把请求当成匿名访问处理。排查这种问题时先检查中间件顺序往往比啃代码快得多。3.4 抽取 JwtTokenHelper 工具类方便复用生成 Token 的逻辑如果在登录接口写一遍在重置密码、第三方登录之类的接口里再写一遍代码很快会散落得到处都是。我的做法是抽一个静态工具类把密钥计算和 Token 生成的逻辑收敛到一处public static class JwtTokenHelper { public static string CreateToken( IEnumerableClaim claims, AuthSettings settings) { var key new SymmetricSecurityKey( Encoding.UTF8.GetBytes(settings.SecretKey)); var credentials new SigningCredentials( key, SecurityAlgorithms.HmacSha256); var now DateTime.UtcNow; var token new JwtSecurityToken( issuer: settings.Issuer, audience: settings.Audience, claims: claims, notBefore: now, expires: now.AddMinutes(settings.TokenExpireMinutes), signingCredentials: credentials); return new JwtSecurityTokenHandler().WriteToken(token); } public static SymmetricSecurityKey GetSecurityKey(string secretKey) { return new SymmetricSecurityKey( Encoding.UTF8.GetBytes(secretKey)); } }这样登录接口只需要构造 Claim 数组然后调用JwtTokenHelper.CreateToken(...)其他接口想要生成辅助 Token 时也一样。抽成静态类在这个场景下足够简单没有内部状态需要管理没必要引入额外的注入服务。更重要的是后面写集成测试时需要快速生成合法 Token这个抽取能直接复用同一套生成逻辑保证测试数据和生产环境的行为完全一致。4. 保护接口并在 Postman 里完成实测4.1 用 [Authorize] 保护接口并读取当前用户信息认证注册完成后给需要保护的 Controller 或 Action 加上[Authorize]特性即可。比如一个查询用户资料的接口[Route(api/[controller])] [ApiController] public class UserController : ControllerBase { [HttpGet(profile)] [Authorize] public IActionResult GetProfile() { var userId User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var userName User.Identity.Name; var role User.FindFirst(ClaimTypes.Role)?.Value; var department User.FindFirst(department)?.Value; return Ok(new { UserId userId, UserName userName, Role role, Department department }); } }User.Identity.Name底层就是在读 Name 类型的 Claim。控制器里读取当前用户身份不再需要查数据库所有信息都来自认证中间件解析好的 ClaimsPrincipal这在微服务场景下非常舒服每个下游服务不用维护用户表也能知道当前操作者是谁、属于什么角色。同时要注意[Authorize]只表示必须登录并不限制谁能访问。角色维度的限制要用[Authorize(Roles Admin)]。另外登录接口本身必须显式加[AllowAnonymous]否则会形成死循环没 Token 进不去接口而 Token 正是从接口里拿的。4.2 Postman 加 Token 的标准姿势接口写完后我用 Postman 做验证。第一次跑的时候最容易犯的错是Token 确实生成出来了但请求头没带对。JWT 的标准携带方式是 HTTP Authorization 请求头值必须是Bearer Token格式Bearer 和 Token 之间有一个空格Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Postman 里也可以直接用 Authorization 选项卡类型选择 Bearer Token把生成的 Token 粘进去发请求时它会自动生成正确的请求头。建议两种方式都试一遍能加深对 Header 格式的理解。Token 内容可以用 jwt.io 这类在线工具解码检查一下 Claims 有没有写对但注意只拿调试环境的 Token 做这种事生产 Token 绝不贴到第三方网站上。4.3 不带 Token、带错误 Token、Token 过期三种场景的响应对比实测不能只看成功路径。我习惯把典型场景整理成表格逐个打一遍确认整套配置真正生效下面这张表可以直接对应到 Postman 的测试用例里测试场景请求头预期状态码说明不带 Token无401匿名访问被拦截带有效 TokenBearer 有效 Token200正常通过Token 内容被篡改Bearer 改过 Payload 的 Token401签名校验失败Token 已过期Bearer 过期 Token401生命周期校验失败密钥不一致Bearer 其他密钥签发的 Token401签名校验失败Bearer 前缀写错直接放 Token 值401认证处理器识别不了我在实测中遇到过一个很隐蔽的问题Token 内容复制对了、Bearer 也写了结果还是 401。后来发现是复制 Token 时末尾多带了一个换行符命令行和脚本环境下经常出现这种隐形字符。遇到 401 先别急着改代码把请求头原样打印出来逐字符检查一遍低级问题往往藏在这种地方。5. 这套 JWT 方案在真实项目中踩过的坑5.1 Claim 被自动重映射DefaultInboundClaimTypeMap 的坑这是 .Net Core 2.x 时代最有名的一个坑。默认情况下JwtSecurityTokenHandler内部维护着入站 Claim 类型映射表解析 Token 时会把短类型名自动改写成ClaimTypes里的长 URI 类型。例如 Token 里的nameid会映射成ClaimTypes.NameIdentifierunique_name映射成ClaimTypes.Name。这个映射平时很省事但一旦你混用两种风格就容易翻车。生成 Token 时用new Claim(user_id, ...)这类自定义短名解析时用User.FindFirst(user_id)本来没问题但如果短名恰好撞进映射表系统会偷偷改成另一个类型名查询结果就是 null。有人排查一整天最后发现是email被映射成了ClaimTypes.Email而代码里是按短名取的。实际项目里我的建议是二选一别两边掺着用。要么全程用ClaimTypes常量生成和读取靠默认映射工作要么在 Startup 构造阶段把两张映射表清空完全按短名读写JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); JwtSecurityTokenHandler.DefaultOutboundClaimTypeMap.Clear();清空之后行为更可预测尤其适合多个语言服务共用一个 JWT 标准的团队大家一律按标准短名读写不需要了解 .Net 内部的 URI 命名空间。还要记住像department这样的自定义字段不在映射表里读写都按写入时的字符串进行不受这个坑影响。5.2 时钟偏差导致 Token 提前失效或过期不灵敏不配置ClockSkew时默认值是 5 分钟。这意味着一个有效期为 30 分钟的 Token最长实际有效 35 分钟反过来notBefore也带同样的偏移。普通业务里这问题不大但涉及支付、密码重置等敏感操作时过期 Token 还能被接受 5 分钟审计一般过不了。另一个关联坑是ValidateLifetime必须显式设成 true。有人抄配置时漏了这行结果 Token 早已越过过期时间却依然被当作有效凭证因为校验器根本没去查生命周期。这两个参数要一起看缺一个都会造成“过期时间形同虚设”的结果。我在生产代码里统一设ValidateLifetime true、ClockSkew TimeSpan.FromSeconds(30)既不敏感也不至于因为服务器时钟的小幅抖动影响正常用户。还有一个容易被忽视的细节生成 Token 时如果用DateTime.Now而不是DateTime.UtcNow在时区设置不同的服务器上exp、nbf会比预期早或晚几个小时表现就是“Token 明明没过期却提示未生效”。这个问题很隐蔽症状还随机建议所有时间相关操作一律走 UTC。5.3 401、403、500 的区分与常见定位手段受保护接口出问题第一件事不是改代码而是分清返回码。401 表示未认证说明请求根本没有被识别成登录用户常见原因是没有UseAuthentication()、请求头格式不对、Token 无效或过期403 表示已认证但权限不足通常是角色 Claim 缺失或[Authorize(Roles ...)]配置不对500 则说明处理时抛了异常比如密钥长度不足、读取 Claim 时空引用等。定位手段按顺序来先从 Postman 确认请求头是不是Bearer Token格式再看 Startup 里认证中间件和 Mvc 的顺序然后看服务端日志。JwtBearer 支持通过事件钩子把认证失败的具体原因暴露出来配置方式如下options.Events new JwtBearerEvents { OnAuthenticationFailed context { if (context.Exception is SecurityTokenExpiredException) { // Token 已过期可以打日志或者单独记录 } return Task.CompletedTask; }, OnChallenge context { // 默认返回空 body 的 401这里可以改成统一 JSON 结构 return Task.CompletedTask; } };OnAuthenticationFailed里能看到具体异常类型可以快速区分过期、签名失败还是格式错误。OnChallenge在触发 401 时执行很多团队在这里改写响应结构把默认的空 body 换成{ code 401, message unauthorized }这类统一格式前后端联调时会省很多沟通成本。5.4 集成测试里怎么快速生成有效 Token改造完认证后我还会顺手写两个集成测试防止后续改动把认证链路弄坏。.Net Core 2.1 项目里可以用Microsoft.AspNetCore.TestHost创建内存测试服务器不需要真的对外监听端口。测试代码里最关键的就是快速造出合法 Token。既然前面已经抽取了JwtTokenHelper这里直接复用生成逻辑[Fact] public async Task GetProfile_With_ValidToken_ReturnsOk() { var server new TestServer(new WebHostBuilder() .UseStartupStartup()); var client server.CreateClient(); var token JwtTokenHelper.CreateToken( new[] { new Claim(ClaimTypes.NameIdentifier, 10001), new Claim(ClaimTypes.Name, tester), new Claim(ClaimTypes.Role, Admin) }, testSettings); client.DefaultRequestHeaders.Authorization new AuthenticationHeaderValue(Bearer, token); var response await client.GetAsync(/api/user/profile); Assert.Equal(HttpStatusCode.OK, response.StatusCode); }testSettings里配置的密钥必须和测试服务启动时读到的配置一致否则签名一定对不上。这个测试写法比把网站真正跑起来更快、更稳定CI 环境里也不会受端口冲突影响。界定好正常路径、401 拦截路径、角色校验路径三组用例认证链路基本就稳了。最后再说一句实际操作中的体会JWT 本身不算复杂复杂的是围绕它的工程化细节——密钥管理、过期策略、事件日志、统一响应体都要提前想清楚。尤其是 .Net Core 2.1 这类老版本项目资料少、坑又多把基础链路和典型报错摸透之后后面不管是升级框架还是对接新服务都会轻松很多。我改造完这套之后又把同样的模式复制到另外两个老服务上一次比一次快就是因为把坑都提前记了下来。 
长河君 · 2026/10/23 9:40:34 · 阅读 1.2k .Net Core 2.1 接入 JWT 身份认证：生成、验证与踩坑实战
前一阵子接手一个维护了三年多的 .Net Core 2.1 服务第一件要补的事就是给接口加身份认证。和我预期的一样方案绕不开 JWT——生成 Token、验证 Token、把用户身份安全地传递到控制器。JWT 认证在 .Net Core 里已经被封装得比较顺手但 2.1 这个版本处在关键的迭代期网上很多教程讲的是 3.x 甚至 5.x 的写法照抄过来经常在包版本、中间件顺序和 Claim 读取上翻车。这篇文章是完整的落地记录覆盖实现过程、配置参数和各类踩坑点正在维护 2.1 老项目的人可以直接参考新手也能借此建立 JWT 认证的整体概念。1. 为什么在 .Net Core 2.1 时代还是坚持用 JWT 做认证1.1 从 Session 到 Token认证方式变迁的底层逻辑在单机 Web 时代最常见的认证方式是 Session Cookie服务器内存里保存一份会话状态浏览器每次请求自动带上 SessionId服务端拿着 SessionId 查会话数据。这套机制胜在直观但在分布式场景下马上暴露问题请求一旦被负载均衡转发到不同实例会话状态就丢失了。解决办法要么做 Session 持久化要么开启负载均衡粘滞会话但无论哪种都会增加架构复杂度和维护成本。JWT 的思路完全不同。它把“用户是谁、能干什么、什么时候失效”这些信息全部编码进一个自包含的 Token 里服务器不再需要保存任何会话状态。客户端把 Token 保存下来每个请求都带上它服务端拿到后只要验签通过、时效没问题就完全信任这个身份。这种无状态特性让 JWT 在 Web API、前后端分离、微服务架构里成了事实标准。.Net Core 2.1 是跨平台体系中较早的 LTS 版本很多企业内部服务到现在依然在线上运行。给这些老服务补上 JWT 身份认证是大量开发者都会遇到的改造任务。理解它的原理和落地细节不只是对付 2.1 项目对后面升级到新框架也同样有价值。1.2 JWT 令牌的三个构成段与一次完整认证流程JWT 全称 JSON Web Token是一个开放标准RFC 7519。一个 Token 由三段用点分隔的 Base64Url 字符串组成Header、Payload、Signature。Header 声明签名算法比如 HS256和 Token 类型Payload 存放声明信息比如用户 ID、角色、过期时间Signature 是用密钥对前两段内容做的签名确保内容没有被篡改。打个比方Token 就像一张盖了公章的通行证Header 和 Payload 是证件上印的内容Signature 是公章。证件内容谁都能读Base64 只编码不加密但没有对应的章密钥任何人改动内容后都补不上新章。所以 JWT 适合做认证而非保密手机号、密码、身份证这类敏感信息绝不要往 Payload 里塞。一次完整的认证流程围绕下面几个动作展开客户端先调用登录接口提交用户名密码服务端校验通过后用密钥把一堆用户声明打包签成 Token 返回客户端保存 Token后续请求在 Authorization 请求头带上Bearer Token服务端通过认证中间件验证签名、签发者、受众和有效期通过后把用户身份挂到 HttpContext.User 上之后的授权判断和业务代码直接读取即可。这套流程看起来简单但真正落到 .Net Core 2.1 项目里有很多容易栽跟头的工程细节比如 NuGet 包版本、中间件注册顺序、Claim 类型映射、时钟偏移。这些细节散落在官方文档和不同版本的博客里说法还经常互相矛盾整理成完整的过程记录比零散搜索效率高得多。下面从环境准备开始把每一步代码和选择背后的理由讲清楚。2. 项目准备目标框架、NuGet 包与配置项设计2.1 创建项目与确认 .Net Core 2.1 的依赖版本很多人在 2.1 项目里加 JWT 失败第一个坑就是 NuGet 包版本装错。.Net Core 2.1 项目文件里TargetFramework要写成netcoreapp2.1Web API 模板默认引用Microsoft.AspNetCore.App元包但 JWT Bearer 认证中间件并不在元包里需要单独安装dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 2.1.2如果使用 Visual Studio 的包管理器搜索Microsoft.AspNetCore.Authentication.JwtBearer后一定要注意版本选择 2.1.x 系列不要顺手选了 3.x、5.x 甚至更高版本。装错版本的直接后果是程序集冲突编译阶段就是一片红色波浪线而且报错信息晦涩难懂排查起来非常浪费时间。安装完成后项目里会出现两个关键依赖Microsoft.AspNetCore.Authentication.JwtBearer提供认证中间件System.IdentityModel.Tokens.Jwt提供JwtSecurityTokenHandler这个生成和解析 Token 的核心类。如果老项目之前装过System.IdentityModel.Tokens.Jwt的旧版本建议统一升到 5.3.0 以上否则个别签名相关 API 会找不到行为表现也很不稳定。2.2 appsettings.json 里的认证参数怎么设计JWT 认证需要配置的核心参数有四个签发者 Issuer、受众 Audience、签名密钥 SecretKey、Token 有效期 TokenExpireMinutes。把它们单独放进一个配置节方便后续替换和读取{ AuthSettings: { Issuer: MyAuthServer, Audience: MyApiClient, SecretKey: Pssw0rd_Strong_Secret_Key_Replace_Me_2024, TokenExpireMinutes: 30 } }Issuer 表示 Token 由哪个服务签发验证端的 ValidIssuer 必须和生成端完全一致Audience 表示 Token 面向哪个客户端系统前后端分离项目里通常填前端应用名或网关名。这两个参数看似简单作用却很关键它们限定 Token 的使用范围防止某个服务签发的 Token 被另一个毫不相关的服务无条件接受相当于给凭证划定了活动边界。TokenExpireMinutes 直接影响安全性和体验。内部管理后台可以放宽到 60 分钟面向 C 端的接口建议 15 到 30 分钟。时间太长Token 泄露后的风险窗口就大时间太短用户频繁被踢下线口碑也受影响。很多团队后续会引入 Refresh Token 机制平衡这两点但有效期这个参数最好从一开始就做成配置项不要写死在代码里。2.3 密钥的安全生成方法与长度要求密钥是整个 JWT 方案里最敏感的资源。HS256 算法要求密钥字节长度至少 128 位16 个字节否则运行时抛异常常见的错误类型是ArgumentOutOfRangeException提示信息里通常带IDX10708类似编号大意是 SecurityKey 的 KeySize 不能小于 128 位。生成 Token 时报错的人特别多基本都是随手敲了一段很短的字符串当密钥。我一般建议用 32 字节以上的随机串既满足安全强度也避免未来调整算法时长度不够用。生成方式可以这样在 PowerShell 里执行[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }) -as [byte[]])把产出的 Base64 字符串填入配置项注意不要把它提交到 Git 仓库。我的习惯是开发环境放在 appsettings.Development.json生产环境从环境变量或部署平台的密钥管理服务读取比如在读取配置时做一层兜底var secretKey Environment.GetEnvironmentVariable(AUTH_SECRET_KEY) ?? Configuration[AuthSettings:SecretKey];还要强调一点JWT 的 HS256 属于对称签名签发方和验证方共用同一个密钥。如果项目里有多个服务要互相验证 Token密钥的分发、轮换必须提前定好规范不能把明文密钥外传或写在代码注释里否则整个认证体系等于没有防线。3. 核心实现Token 生成、认证注册与中间件接线3.1 登录接口里的 Token 生成逻辑Token 生成的核心是先用用户信息构造一组 Claim声明再用密钥签名。为了代码整洁我先定义一个配置实体类方便依赖注入和测试复用public class AuthSettings { public string Issuer { get; set; } public string Audience { get; set; } public string SecretKey { get; set; } public int TokenExpireMinutes { get; set; } }在登录接口中用户密码校验通过后把用户信息封装成 Claim 数组然后创建并序列化 Tokenprivate string GenerateToken(UserAuthModel user, AuthSettings settings) { var claims new[] { new Claim(ClaimTypes.NameIdentifier, user.UserId.ToString()), new Claim(ClaimTypes.Name, user.UserName), new Claim(ClaimTypes.Role, user.Role), new Claim(department, user.Department), }; var key new SymmetricSecurityKey(Encoding.UTF8.GetBytes(settings.SecretKey)); var credentials new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var now DateTime.UtcNow; var token new JwtSecurityToken( issuer: settings.Issuer, audience: settings.Audience, claims: claims, notBefore: now, expires: now.AddMinutes(settings.TokenExpireMinutes), signingCredentials: credentials); return new JwtSecurityTokenHandler().WriteToken(token); }这里有几个容易被忽略的细节。Claim 相当于是 Token 里声明的字段建议只放认证和授权需要的最小信息比如用户 ID、用户名、角色、部门手机号身份证这类敏感信息绝对不要放进去因为 JWT 的 Payload 只是 Base64 编码任何拿到 Token 的人都能直接解码读出内容。notBefore表示生效时间expires表示过期时间统一用DateTime.UtcNow避免服务器时区差异导致 Token 生效时间错乱。SecurityAlgorithms.HmacSha256是这次使用的对称签名算法也可以换 HmacSha512但 HS256 在各语言平台上的解析库兼容性最好跨服务调用时不建议为了追求强度随意换算法。WriteToken负责把内存里的 Token 对象序列化成最终字符串这个字符串就是客户端要保存并在后续请求中携带的凭证。3.2 Startup.ConfigureServices 里的认证服务注册生成 Token 只完成了一半关键的另一半是让服务端自动验证每个请求携带的 Token。这个能力要在 Startup 的ConfigureServices里注册public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1); var authSettings Configuration.GetSection(AuthSettings).GetAuthSettings(); services.AddSingleton(authSettings); var key new SymmetricSecurityKey(Encoding.UTF8.GetBytes(authSettings.SecretKey)); services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidIssuer authSettings.Issuer, ValidateAudience true, ValidAudience authSettings.Audience, ValidateIssuerSigningKey true, IssuerSigningKey key, ValidateLifetime true, ClockSkew TimeSpan.FromSeconds(30) }; }); }AddAuthentication注册认证框架AddJwtBearer把具体的认证处理器挂上去。TokenValidationParameters是验证参数集合每一行都对应一个独立的校验动作。ValidateIssuer、ValidateAudience、ValidateIssuerSigningKey 这三项建议全部显式打开不要偷懒只留一个签名校验否则将来做安全审计的时候很难交代清楚。ClockSkew很多人不重视。分布式系统里不同服务器时间可能有微小偏差所以认证处理默认允许长达 5 分钟的时钟偏移也就是说 Token 过期后最长 5 分钟内依然可能被接受。默认值对普通业务无所谓但对支付、改密这类敏感接口5 分钟的安全窗口过大了。实际项目里我统一调成 30 秒既不敏感也能扛住正常的时钟抖动。3.3 中间件管道的顺序UseAuthentication 到底该放哪光注册服务还不够还需要在请求管线上启用认证中间件。这一步最容易翻车因为平台不会报错只是所有带 Token 的请求都验证不过。.Net Core 2.1 的 Startup 中Configure方法里正确的顺序是这样public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseAuthentication(); app.UseMvc(); }原则一句话UseAuthentication必须在UseMvc之前。可以这样理解中间件是一串排队执行的关卡Mvc 一旦接管请求后续关卡就没机会执行了。把认证放在 Mvc 前面请求在进入路由和控制器之前Token 就已经被解析好并把用户身份写进 HttpContext.User控制器里的[Authorize]判断身份才有据可依。如果不写UseAuthentication()会出现一个非常迷惑的现象生成 Token 正常、配置文件看着也没问题但访问受保护接口永远 401。原因就是认证中间件根本没有运行HttpContext.User 一直是空的授权过滤器永远把请求当成匿名访问处理。排查这种问题时先检查中间件顺序往往比啃代码快得多。3.4 抽取 JwtTokenHelper 工具类方便复用生成 Token 的逻辑如果在登录接口写一遍在重置密码、第三方登录之类的接口里再写一遍代码很快会散落得到处都是。我的做法是抽一个静态工具类把密钥计算和 Token 生成的逻辑收敛到一处public static class JwtTokenHelper { public static string CreateToken( IEnumerableClaim claims, AuthSettings settings) { var key new SymmetricSecurityKey( Encoding.UTF8.GetBytes(settings.SecretKey)); var credentials new SigningCredentials( key, SecurityAlgorithms.HmacSha256); var now DateTime.UtcNow; var token new JwtSecurityToken( issuer: settings.Issuer, audience: settings.Audience, claims: claims, notBefore: now, expires: now.AddMinutes(settings.TokenExpireMinutes), signingCredentials: credentials); return new JwtSecurityTokenHandler().WriteToken(token); } public static SymmetricSecurityKey GetSecurityKey(string secretKey) { return new SymmetricSecurityKey( Encoding.UTF8.GetBytes(secretKey)); } }这样登录接口只需要构造 Claim 数组然后调用JwtTokenHelper.CreateToken(...)其他接口想要生成辅助 Token 时也一样。抽成静态类在这个场景下足够简单没有内部状态需要管理没必要引入额外的注入服务。更重要的是后面写集成测试时需要快速生成合法 Token这个抽取能直接复用同一套生成逻辑保证测试数据和生产环境的行为完全一致。4. 保护接口并在 Postman 里完成实测4.1 用 [Authorize] 保护接口并读取当前用户信息认证注册完成后给需要保护的 Controller 或 Action 加上[Authorize]特性即可。比如一个查询用户资料的接口[Route(api/[controller])] [ApiController] public class UserController : ControllerBase { [HttpGet(profile)] [Authorize] public IActionResult GetProfile() { var userId User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var userName User.Identity.Name; var role User.FindFirst(ClaimTypes.Role)?.Value; var department User.FindFirst(department)?.Value; return Ok(new { UserId userId, UserName userName, Role role, Department department }); } }User.Identity.Name底层就是在读 Name 类型的 Claim。控制器里读取当前用户身份不再需要查数据库所有信息都来自认证中间件解析好的 ClaimsPrincipal这在微服务场景下非常舒服每个下游服务不用维护用户表也能知道当前操作者是谁、属于什么角色。同时要注意[Authorize]只表示必须登录并不限制谁能访问。角色维度的限制要用[Authorize(Roles Admin)]。另外登录接口本身必须显式加[AllowAnonymous]否则会形成死循环没 Token 进不去接口而 Token 正是从接口里拿的。4.2 Postman 加 Token 的标准姿势接口写完后我用 Postman 做验证。第一次跑的时候最容易犯的错是Token 确实生成出来了但请求头没带对。JWT 的标准携带方式是 HTTP Authorization 请求头值必须是Bearer Token格式Bearer 和 Token 之间有一个空格Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Postman 里也可以直接用 Authorization 选项卡类型选择 Bearer Token把生成的 Token 粘进去发请求时它会自动生成正确的请求头。建议两种方式都试一遍能加深对 Header 格式的理解。Token 内容可以用 jwt.io 这类在线工具解码检查一下 Claims 有没有写对但注意只拿调试环境的 Token 做这种事生产 Token 绝不贴到第三方网站上。4.3 不带 Token、带错误 Token、Token 过期三种场景的响应对比实测不能只看成功路径。我习惯把典型场景整理成表格逐个打一遍确认整套配置真正生效下面这张表可以直接对应到 Postman 的测试用例里测试场景请求头预期状态码说明不带 Token无401匿名访问被拦截带有效 TokenBearer 有效 Token200正常通过Token 内容被篡改Bearer 改过 Payload 的 Token401签名校验失败Token 已过期Bearer 过期 Token401生命周期校验失败密钥不一致Bearer 其他密钥签发的 Token401签名校验失败Bearer 前缀写错直接放 Token 值401认证处理器识别不了我在实测中遇到过一个很隐蔽的问题Token 内容复制对了、Bearer 也写了结果还是 401。后来发现是复制 Token 时末尾多带了一个换行符命令行和脚本环境下经常出现这种隐形字符。遇到 401 先别急着改代码把请求头原样打印出来逐字符检查一遍低级问题往往藏在这种地方。5. 这套 JWT 方案在真实项目中踩过的坑5.1 Claim 被自动重映射DefaultInboundClaimTypeMap 的坑这是 .Net Core 2.x 时代最有名的一个坑。默认情况下JwtSecurityTokenHandler内部维护着入站 Claim 类型映射表解析 Token 时会把短类型名自动改写成ClaimTypes里的长 URI 类型。例如 Token 里的nameid会映射成ClaimTypes.NameIdentifierunique_name映射成ClaimTypes.Name。这个映射平时很省事但一旦你混用两种风格就容易翻车。生成 Token 时用new Claim(user_id, ...)这类自定义短名解析时用User.FindFirst(user_id)本来没问题但如果短名恰好撞进映射表系统会偷偷改成另一个类型名查询结果就是 null。有人排查一整天最后发现是email被映射成了ClaimTypes.Email而代码里是按短名取的。实际项目里我的建议是二选一别两边掺着用。要么全程用ClaimTypes常量生成和读取靠默认映射工作要么在 Startup 构造阶段把两张映射表清空完全按短名读写JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); JwtSecurityTokenHandler.DefaultOutboundClaimTypeMap.Clear();清空之后行为更可预测尤其适合多个语言服务共用一个 JWT 标准的团队大家一律按标准短名读写不需要了解 .Net 内部的 URI 命名空间。还要记住像department这样的自定义字段不在映射表里读写都按写入时的字符串进行不受这个坑影响。5.2 时钟偏差导致 Token 提前失效或过期不灵敏不配置ClockSkew时默认值是 5 分钟。这意味着一个有效期为 30 分钟的 Token最长实际有效 35 分钟反过来notBefore也带同样的偏移。普通业务里这问题不大但涉及支付、密码重置等敏感操作时过期 Token 还能被接受 5 分钟审计一般过不了。另一个关联坑是ValidateLifetime必须显式设成 true。有人抄配置时漏了这行结果 Token 早已越过过期时间却依然被当作有效凭证因为校验器根本没去查生命周期。这两个参数要一起看缺一个都会造成“过期时间形同虚设”的结果。我在生产代码里统一设ValidateLifetime true、ClockSkew TimeSpan.FromSeconds(30)既不敏感也不至于因为服务器时钟的小幅抖动影响正常用户。还有一个容易被忽视的细节生成 Token 时如果用DateTime.Now而不是DateTime.UtcNow在时区设置不同的服务器上exp、nbf会比预期早或晚几个小时表现就是“Token 明明没过期却提示未生效”。这个问题很隐蔽症状还随机建议所有时间相关操作一律走 UTC。5.3 401、403、500 的区分与常见定位手段受保护接口出问题第一件事不是改代码而是分清返回码。401 表示未认证说明请求根本没有被识别成登录用户常见原因是没有UseAuthentication()、请求头格式不对、Token 无效或过期403 表示已认证但权限不足通常是角色 Claim 缺失或[Authorize(Roles ...)]配置不对500 则说明处理时抛了异常比如密钥长度不足、读取 Claim 时空引用等。定位手段按顺序来先从 Postman 确认请求头是不是Bearer Token格式再看 Startup 里认证中间件和 Mvc 的顺序然后看服务端日志。JwtBearer 支持通过事件钩子把认证失败的具体原因暴露出来配置方式如下options.Events new JwtBearerEvents { OnAuthenticationFailed context { if (context.Exception is SecurityTokenExpiredException) { // Token 已过期可以打日志或者单独记录 } return Task.CompletedTask; }, OnChallenge context { // 默认返回空 body 的 401这里可以改成统一 JSON 结构 return Task.CompletedTask; } };OnAuthenticationFailed里能看到具体异常类型可以快速区分过期、签名失败还是格式错误。OnChallenge在触发 401 时执行很多团队在这里改写响应结构把默认的空 body 换成{ code 401, message unauthorized }这类统一格式前后端联调时会省很多沟通成本。5.4 集成测试里怎么快速生成有效 Token改造完认证后我还会顺手写两个集成测试防止后续改动把认证链路弄坏。.Net Core 2.1 项目里可以用Microsoft.AspNetCore.TestHost创建内存测试服务器不需要真的对外监听端口。测试代码里最关键的就是快速造出合法 Token。既然前面已经抽取了JwtTokenHelper这里直接复用生成逻辑[Fact] public async Task GetProfile_With_ValidToken_ReturnsOk() { var server new TestServer(new WebHostBuilder() .UseStartupStartup()); var client server.CreateClient(); var token JwtTokenHelper.CreateToken( new[] { new Claim(ClaimTypes.NameIdentifier, 10001), new Claim(ClaimTypes.Name, tester), new Claim(ClaimTypes.Role, Admin) }, testSettings); client.DefaultRequestHeaders.Authorization new AuthenticationHeaderValue(Bearer, token); var response await client.GetAsync(/api/user/profile); Assert.Equal(HttpStatusCode.OK, response.StatusCode); }testSettings里配置的密钥必须和测试服务启动时读到的配置一致否则签名一定对不上。这个测试写法比把网站真正跑起来更快、更稳定CI 环境里也不会受端口冲突影响。界定好正常路径、401 拦截路径、角色校验路径三组用例认证链路基本就稳了。最后再说一句实际操作中的体会JWT 本身不算复杂复杂的是围绕它的工程化细节——密钥管理、过期策略、事件日志、统一响应体都要提前想清楚。尤其是 .Net Core 2.1 这类老版本项目资料少、坑又多把基础链路和典型报错摸透之后后面不管是升级框架还是对接新服务都会轻松很多。我改造完这套之后又把同样的模式复制到另外两个老服务上一次比一次快就是因为把坑都提前记了下来。