本系列专栏基于杨中科老师的《ASP.NET Core技术内幕与项目 实战》本人记录梳理的学习笔记有部分的增补和省略。更全面系统的讲解请看杨老师的视频课【.NET教程.Net Core视频教程杨中科主讲】。一、JWT 基础概念1. 传统Session在单体应用中用户登录状态保存在服务器内存的Session中简单高效。但在分布式 / 集群环境中多台服务器内存不共享Session 无法跨服务器同步。虽然可以用 Redis、Memcached 做中心状态服务器统一存储 Session但会增加网络开销、单点故障风险和性能瓶颈。2. JWT 核心原理JWTJSON Web Token是一种轻量级的客户端存储令牌方案彻底解决分布式身份认证问题用户登录成功后服务器生成加密签名的令牌Token返回给客户端客户端自行保存令牌LocalStorage/Cookie/ 小程序缓存等后续每次请求客户端在请求头携带令牌服务器只用校验签名合法性无需查询会话存储无状态、可横向扩展安全保障令牌使用服务器独享密钥进行签名客户端无法伪造服务器收到令牌后先验签再解析内容Payload负载是明文编码绝对不能存放密码、密钥等敏感信息3. JWT 标准结构JWT 由三部分组成用.分隔Header头部声明加密算法、令牌类型Payload负载存放用户非敏感信息用户 ID、角色、过期时间等Signature签名服务器对前两部分的签名防篡改二、JWT 基础使用前置依赖安装 JWT 核心 NuGet 包Install-Package System.IdentityModel.Tokens.Jwt1. 生成 JWT 令牌using System.IdentityModel.Tokens.Jwt; using System.Security.Claims; using System.Text; using Microsoft.IdentityModel.Tokens; // 1. 创建用户声明存放用户身份信息非敏感数据 var claims new ListClaim { // 系统内置声明类型 new Claim(ClaimTypes.NameIdentifier, 1), // 用户ID new Claim(ClaimTypes.Name, yzk), // 用户名 // 多角色声明 new Claim(ClaimTypes.Role, User), new Claim(ClaimTypes.Role, Admin), // 自定义声明 new Claim(PassPort, E90000082) }; // 2. 配置密钥生产环境务必使用复杂密钥存入配置文件不要硬编码 string secretKey fasdfad9045dafz222#fadpio0232; // 令牌过期时间 DateTime expires DateTime.Now.AddDays(1); // 3. 创建签名密钥和凭证 byte[] keyBytes Encoding.UTF8.GetBytes(secretKey); var securityKey new SymmetricSecurityKey(keyBytes); // 使用 HMAC-SHA256 签名算法 var signingCredentials new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256); // 4. 生成 JWT 令牌 var tokenDescriptor new JwtSecurityToken( claims: claims, expires: expires, signingCredentials: signingCredentials ); string jwtToken new JwtSecurityTokenHandler().WriteToken(tokenDescriptor); // 输出最终令牌 Console.WriteLine(生成的JWT令牌\n jwtToken);2. 手动解码 JWTJWT 的 Header 和 Payload 只是Base64Url 编码不是加密可直接解码查看/// summary /// JWT Base64Url 解码工具方法 /// /summary string JwtDecode(string s) { // 替换 Base64Url 特殊字符 s s.Replace(-, ).Replace(_, /); // 补全 Base64 补齐符 switch (s.Length % 4) { case 2: s ; break; case 3: s ; break; } var bytes Convert.FromBase64String(s); return Encoding.UTF8.GetString(bytes); } // 使用示例 string[] tokenSegments jwtToken.Split(.); string header JwtDecode(tokenSegments[0]); string payload JwtDecode(tokenSegments[1]); Console.WriteLine(--- Header ---); Console.WriteLine(header); Console.WriteLine(--- Payload ---); Console.WriteLine(payload);3. 安全校验并解析 JWT必须验签才能保证令牌未被篡改这是服务端解析的标准方式string secretKey fasdfad9045dafz222#fadpio0232; JwtSecurityTokenHandler tokenHandler new JwtSecurityTokenHandler(); // 配置校验规则 TokenValidationParameters validationParams new TokenValidationParameters { // 签名密钥必须和签发时一致 IssuerSigningKey new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey)), // 关闭发行方校验简单场景 ValidateIssuer false, // 关闭受众校验简单场景 ValidateAudience false, // 开启过期时间校验 ValidateLifetime true }; // 校验并解析令牌验签失败会直接抛出异常 ClaimsPrincipal claimsPrincipal tokenHandler.ValidateToken( jwtToken, validationParams, out SecurityToken validatedToken ); // 读取解析后的用户信息 foreach (var claim in claimsPrincipal.Claims) { Console.WriteLine(${claim.Type} {claim.Value}); }三、封装 JWT 认证1. 配置文件定义 JWT 参数appsettings.json中添加 JWT 配置节点JWT: { SigningKey: fasdfad9045dafz222#fadpio0232, // 密钥 ExpireSeconds: 86400 // 过期时间秒1天86400秒 }2. 创建配置实体类/// summary /// JWT 配置选项 /// /summary public class JWTOptions { /// summary /// 签名密钥 /// /summary public string SigningKey { get; set; } /// summary /// 过期时间秒 /// /summary public int ExpireSeconds { get; set; } }3. 注册 JWT 认证服务安装认证专用 NuGet 包Install-Package Microsoft.AspNetCore.Authentication.JwtBearerProgram.cs中配置服务// 绑定 JWT 配置 builder.Services.ConfigureJWTOptions(builder.Configuration.GetSection(JWT)); // 启用 JWT 身份认证 builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { // 读取配置 var jwtOptions builder.Configuration.GetSection(JWT).GetJWTOptions(); byte[] keyBytes Encoding.UTF8.GetBytes(jwtOptions.SigningKey); var securityKey new SymmetricSecurityKey(keyBytes); // 令牌校验规则 options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer false, // 不校验发行方 ValidateAudience false, // 不校验受众 ValidateLifetime true, // 必须校验过期时间 ValidateIssuerSigningKey true, // 必须校验签名密钥 IssuerSigningKey securityKey }; }); // Swagger 配置后面补充 // ... var app builder.Build(); // 核心中间件顺序不能错 app.UseAuthentication(); // 1. 身份验证校验令牌 app.UseAuthorization(); // 2. 授权验证校验角色/权限 app.MapControllers(); app.Run();4. 封装通用 JWT 生成方法创建工具类方便控制器调用using Microsoft.Extensions.Options; using System.IdentityModel.Tokens.Jwt; using System.Security.Claims; using System.Text; using Microsoft.IdentityModel.Tokens; public interface IJwtService { string GenerateToken(ListClaim claims); } public class JwtService : IJwtService { private readonly JWTOptions _jwtOptions; // 依赖注入配置 public JwtService(IOptionsJWTOptions jwtOptions) { _jwtOptions jwtOptions.Value; } /// summary /// 生成 JWT 令牌 /// /summary public string GenerateToken(ListClaim claims) { var keyBytes Encoding.UTF8.GetBytes(_jwtOptions.SigningKey); var securityKey new SymmetricSecurityKey(keyBytes); var credentials new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256); var token new JwtSecurityToken( claims: claims, expires: DateTime.Now.AddSeconds(_jwtOptions.ExpireSeconds), signingCredentials: credentials ); return new JwtSecurityTokenHandler().WriteToken(token); } } // Program.cs 注册服务 builder.Services.AddScopedIJwtService, JwtService();5. 登录接口实现结合 Identityusing Microsoft.AspNetCore.Identity; using Microsoft.AspNetCore.Mvc; using System.Security.Claims; [ApiController] [Route(api/[controller])] public class AccountController : ControllerBase { private readonly UserManagerIdentityUser _userManager; private readonly IJwtService _jwtService; public AccountController(UserManagerIdentityUser userManager, IJwtService jwtService) { _userManager userManager; _jwtService jwtService; } [HttpPost(login)] public async TaskIActionResult Login(string userName, string password) { // 1. 校验用户密码 var user await _userManager.FindByNameAsync(userName); if (user null || !await _userManager.CheckPasswordAsync(user, password)) { return BadRequest(用户名或密码错误); } // 2. 创建声明 var claims new ListClaim { new Claim(ClaimTypes.NameIdentifier, user.Id), new Claim(ClaimTypes.Name, user.UserName) }; // 3. 添加角色声明 var roles await _userManager.GetRolesAsync(user); foreach (var role in roles) { claims.Add(new Claim(ClaimTypes.Role, role)); } // 4. 生成令牌 var token _jwtService.GenerateToken(claims); return Ok(new { Token token }); } }6. 受保护接口 获取用户信息添加[Authorize]即可保护接口通过User对象直接获取登录信息[ApiController] [Route(api/[controller])] [Authorize] // 整个控制器需要登录 public class TestController : ControllerBase { [HttpGet(hello)] public IActionResult Hello() { // 从 User 中读取解析后的 JWT 信息 string userId User.FindFirstValue(ClaimTypes.NameIdentifier)!; string userName User.FindFirstValue(ClaimTypes.Name)!; var roles User.FindAll(ClaimTypes.Role).Select(c c.Value); string roleNames string.Join(,, roles); return Ok($用户ID{userId}用户名{userName}角色{roleNames}); } [AllowAnonymous] // 开放接口无需登录 [HttpGet(public)] public IActionResult Public() { return Ok(公共接口所有人可访问); } }7. 请求调用规范使用 Postman / Swagger 调用时请求头Authorization值格式Bearer [你的JWT令牌]注意Bearer和令牌之间必须有且仅有一个空格不能有多余空格、换行8. 客户端存储 JWT 方案Web 端localStorage/sessionStorage/ 加密 Cookie小程序 / App全局变量 本地缓存如微信小程序 wx.setStorageSync安全建议Web 端推荐使用HttpOnly Cookie存储防止 XSS 攻击9. JWT 退出登录客户端退出直接删除本地存储的令牌即可服务端退出JWT 无状态无法直接失效需要额外方案四、[Authorize] 特性使用注意事项中间件顺序是核心必须先UseAuthentication()再UseAuthorization()顺序颠倒会直接导致 401 错误。精细控制权限控制器加[Authorize]所有接口需要登录接口加[Authorize]仅当前接口需要登录[AllowAnonymous]忽略验证优先级最高角色校验[Authorize(Roles Admin)]自动解析机制ASP.NET Core 会自动从请求头读取Authorization、验签、解析、赋值给User对象无需手动编码。401 无详细错误排查常见原因令牌过期签名密钥不一致请求头格式错误缺少 Bearer / 空格错误中间件顺序错误令牌被篡改五、Swagger 集成 JWT 认证调试在Program.cs完善 Swagger 配置支持界面直接输入令牌builder.Services.AddSwaggerGen(c { // 定义 JWT 认证方案 var securityScheme new OpenApiSecurityScheme { Name Authorization, Type SecuritySchemeType.ApiKey, In ParameterLocation.Header, Description 输入格式Bearer {你的JWT令牌}\n示例Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..., Scheme Bearer, BearerFormat JWT, Reference new OpenApiReference { Type ReferenceType.SecurityScheme, Id Bearer } }; c.AddSecurityDefinition(Bearer, securityScheme); // 启用全局安全要求 var securityRequirement new OpenApiSecurityRequirement { { securityScheme, new string[] {} } }; c.AddSecurityRequirement(securityRequirement); });使用Swagger 界面点击「Authorize」按钮输入Bearer 令牌即可调试。六、解决令牌无法提前撤回1. 问题说明JWT 是无状态永久有效的在过期前用户被禁用 / 删除令牌仍能使用令牌被盗用无法立即失效无法实现单设备登录2. 解决方案基于 Version 版本控制轻量、高效、无需大量 Redis 存储适合绝大多数业务步骤 1给用户实体添加版本字段public class ApplicationUser : IdentityUser { /// summary /// JWT 版本号每次登录/禁用用户时自增 /// /summary public long JWTVersion { get; set; } 1; }步骤 2登录时更新版本并写入令牌登录接口中添加// 每次登录版本号1 user.JWTVersion; await _userManager.UpdateAsync(user); // 把版本号写入 JWT claims.Add(new Claim(JWTVersion, user.JWTVersion.ToString()));步骤 3全局校验过滤器using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Mvc.Filters; using Microsoft.AspNetCore.Identity; using System.Security.Claims; public class JwtValidationFilter : IAuthorizationFilter { private readonly UserManagerApplicationUser _userManager; public JwtValidationFilter(UserManagerApplicationUser userManager) { _userManager userManager; } public void OnAuthorization(AuthorizationFilterContext context) { // 允许匿名的接口跳过校验 bool allowAnonymous context.ActionDescriptor.EndpointMetadata .Any(m m is AllowAnonymousAttribute); if (allowAnonymous) return; // 读取 JWT 中的版本号 var jwtVersionStr context.HttpContext.User.FindFirstValue(JWTVersion); if (string.IsNullOrEmpty(jwtVersionStr) || !long.TryParse(jwtVersionStr, out long jwtVersion)) { context.Result new UnauthorizedResult(); return; } // 获取用户ID var userId context.HttpContext.User.FindFirstValue(ClaimTypes.NameIdentifier); var user _userManager.FindByIdAsync(userId).Result; // 校验版本号是否一致不一致则令牌失效 if (user null || user.JWTVersion ! jwtVersion) { context.Result new UnauthorizedResult(); return; } } }步骤 4注册全局过滤器 性能优化// 注册全局过滤器 builder.Services.AddMvc(options { options.Filters.AddJwtValidationFilter(); }); // 性能优化用户信息 JWTVersion 加入内存缓存避免每次请求查库3. 其他撤回方案Redis 黑名单把需要作废的令牌存入 Redis请求时校验双令牌机制access_token短有效期refresh_token长有效期最佳实践高频撤回需求如后台管理系统建议使用 Session Redis总结JWT无状态、分布式友好、服务端无需存储会话开发流程配置 → 签发令牌 → 校验解析 → 权限控制安全Payload 明文不存敏感信息密钥严格保管。优化通过JWTVersion实现令牌主动失效兼顾安全与性能。中间件顺序Authentication必须在Authorization之前。调试工具Swagger 集成 JWT提升开发效率。