咨询JWT Token在ASP.NET Core Web API中的工作机制与认证实现方法

一、Access Token（JWT）与Refresh Token的核心关联规则 #

• 定位拆分：Access Token（也就是常说的JWT）是短有效期、无状态的访问凭证，每次请求受保护接口时由客户端携带，服务端仅通过验签、校验过期时间判断合法性，不需要持久化存储；Refresh Token是长有效期、有状态的纯随机字符串，本身不承载任何用户权限信息，唯一作用是在Access Token过期后，向认证接口换取新的Access Token，避免用户重复输入账号密码。
• 绑定规则：
  • 生成时强关联用户唯一标识（如用户ID），Refresh Token本身为全局唯一的高熵随机字符串（长度不低于128位），不要携带任何明文用户信息
  • 服务端必须持久化存储Refresh Token的全量信息，映射关系包含：Refresh Token本身、关联用户ID、过期时间、是否被主动吊销、关联的签发时间
  • 校验逻辑：客户端持Refresh Token申请新Access Token时，服务端依次校验：① 数据库中存在未被吊销、未过期的匹配记录；② 关联的用户账号状态正常；③ 校验通过后生成新的Access Token，建议同步轮换新的Refresh Token，将旧Token标记为已吊销，降低Token被盗用后的有效攻击窗口
  • 主动失效逻辑：用户注销、修改密码、触发风控时，直接将存储的Refresh Token标记为已吊销即可，无需等待JWT自然过期

二、JWT（Access Token）的具体生成逻辑 #

严格按照RFC规范拆解三步生成流程：

1. 头部段（Header）生成：声明使用的签名算法（内网/单体服务用HS256对称加密，跨服务分布式场景用RS256非对称加密）、Token类型为JWT，将结构化内容做Base64Url编码
2. 载荷段（Payload）生成：也就是校验用的Claims集合，注意该段仅做Base64编码，不具备加密效果，不要塞敏感明文信息。一般包含两类内容：
   • 标准注册声明：exp（过期时间戳，建议设置为15-30分钟）、iss（Token签发方）、aud（Token接收方）、sub（用户唯一标识）
   • 授权类自定义声明：用户角色、细粒度权限标识等，供后续接口授权校验使用
     同样将Claims集合做Base64Url编码
3. 签名段（Signature）生成：将编码后的Header和Payload用英文句号拼接，用配置好的签名密钥（HS256为对称密钥，RS256为签名私钥）对拼接内容做哈希签名，再将签名结果做Base64Url编码
4. 最终返回给客户端的Access Token为三段内容用英文句号拼接的字符串。核心特性：服务端不需要存储Access Token，只要验签通过、未超出过期时间，即可确认身份合法。

三、ASP.NET Core Web API 落地实现步骤 #

1. 依赖与配置准备
   • 通过Nuget引入官方包：Microsoft.AspNetCore.Authentication.JwtBearer
   • 在appsettings.json新增配置节点，不要将密钥硬编码到代码中：

   "JwtConfig": {
     "SecretKey": "长度至少32位的强随机字符串",
     "Issuer": "当前API服务的域名/标识",
     "Audience": "前端调用端的域名/标识",
     "AccessTokenExpireMinutes": 30,
     "RefreshTokenExpireDays": 7
   }
   

2. JWT认证服务注册
   在Program.cs中配置认证服务，指定Token校验规则：

   builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
       .AddJwtBearer(options =>
       {
           options.TokenValidationParameters = new TokenValidationParameters
           {
               ValidateIssuer = true,
               ValidateAudience = true,
               ValidateLifetime = true,
               ValidateIssuerSigningKey = true,
               ValidIssuer = builder.Configuration["JwtConfig:Issuer"],
               ValidAudience = builder.Configuration["JwtConfig:Audience"],
               IssuerSigningKey = new SymmetricSecurityKey(
                   Encoding.UTF8.GetBytes(builder.Configuration["JwtConfig:SecretKey"]!))
           };
       });
   // 注意要在中间件管道中注册：app.UseAuthentication(); app.UseAuthorization();
   

3. 核心逻辑实现
   • JWT生成方法：按照之前拆解的三步逻辑，封装生成Access Token的通用方法：

   private string GenerateAccessToken(ClaimsIdentity userClaims, IConfiguration config)
   {
       var securityKey = new SymmetricSecurityKey(
           Encoding.UTF8.GetBytes(config["JwtConfig:SecretKey"]!));
       var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
       var expireMin = int.Parse(config["JwtConfig:AccessTokenExpireMinutes"]!);
       
       var token = new JwtSecurityToken(
           issuer: config["JwtConfig:Issuer"],
           audience: config["JwtConfig:Audience"],
           claims: userClaims.Claims,
           expires: DateTime.UtcNow.AddMinutes(expireMin),
           signingCredentials: credentials
       );
       return new JwtSecurityTokenHandler().WriteToken(token);
   }
   

   • Refresh Token存储：新建数据库表持久化Refresh Token记录，字段包含：Refresh Token随机串、关联用户ID、过期时间、是否吊销、创建时间
   • 核心接口开发：
     • 登录接口：校验账号密码通过后，组装用户Claims生成Access Token，同时生成高熵随机字符串作为Refresh Token，按配置的过期时间写入数据库表，最终将两个Token返回给客户端
     • 刷新Token接口：接收客户端传入的Refresh Token，查询数据库匹配有效（未过期、未吊销）的记录，定位到对应用户后，重新生成Access Token（同步轮换新的Refresh Token，将旧记录标记为吊销），返回新的Token对
     • 注销接口：将当前用户对应的Refresh Token记录标记为已吊销，实现Token主动失效
   • 授权控制：对需要身份校验的接口添加[Authorize]特性，对登录、刷新Token这类公开接口添加[AllowAnonymous]特性，配置基于Claims的角色、权限校验规则。

实战踩坑提示

• 不要在JWT的Payload中存储用户密码、敏感联系方式这类明文信息，因为JWT的Payload是Base64编码，任何人拿到Token都可以直接解码查看内容，没有加密保护
• 所有过期时间统一用UTC时间计算，不要依赖服务器本地时区，避免时区差异导致的过期判断错误
• 不要给Access Token设置过长的过期时间（如数天、数周），否则Token泄露后的安全风险会大幅提升
• 不要仅靠客户端存储Refresh Token实现无状态认证，没有服务端持久化就无法实现Token的主动吊销，存在被重放攻击的风险

内容的提问来源于stack exchange，提问作者Luther