HMENetCore.Jwt 6.0.52

HMENetCore.Jwt

简介

HMENetCore.Jwt 是一个为 ASP.NET Core 应用提供 JWT 认证相关功能的扩展库，包含 JWT 令牌生成、解析、验证以及 Swagger 集成和鉴权等功能。

功能特性

• JWT 令牌生成：支持自定义 claims 和多种配置方式
• JWT 令牌解析：从令牌中提取 payload 数据
• JWT 认证中间件：简化 JWT 认证配置
• Swagger 集成：自动添加 JWT 认证支持到 Swagger UI
• 多方式获取令牌：支持从 Header、Query、Form 等多种方式获取令牌

运行环境

• 跨平台支持: Supports .NET Standard 2.1, .NET 6, .NET 8, and .NET 9.

安装

dotnet add package HMENetCore.Jwt

使用说明

1. JWT 配置

appsettings.json配置：

{
  "JWT": {
    "Issuer": "your_issuer",
    "AccessTokenAudience": "your_audience",
    "SecurityKey": "your_security_key_at_least_16_chars",
    "AccessTokenExpires": 120,
    "AuthorizationKey": "Authorization"
  }
}

2. 配置 JWT 认证

// 使用默认配置
builder.Services.AddJWTAuthentications(Configuration.GetSection("JWT").Get<JWTConfig>());

// 或者使用自定义配置
builder.Services.AddJWTAuthentications(options => {
    options.Issuer = "custom_issuer";
    options.AccessTokenAudience = "custom_audience";
    options.SecurityKey = "custom_security_key";
    options.AccessTokenExpires = 60;
});

3. 生成 JWT 令牌

public class AuthController : ControllerBase
{
    private readonly JWTConfig _jwtConfig;
    
    public AuthController(IConfiguration configuration)
    {
        _jwtConfig = configuration.GetSection("JWT").Get<JWTConfig>();
    }
    
    [HttpPost("login")]
    public async Task<IActionResult> Login([FromBody] LoginModel model)
    {
        // 验证用户逻辑...
        
        var tokenModel = new JwtTokenModel {
            UserId = user.Id,
            UserName = user.UserName,
            Role = user.Role
        };
        
        var token = await JwtTokenHelper.CreateToken(tokenModel, _jwtConfig);
        
        return Ok(new {
            token = token.accressToken,
            expires = token.expiresTime
        });
    }
}

4. 解析 JWT 令牌

[HttpGet("profile")]
[Authorize]
public IActionResult GetProfile()
{
    // 从请求中获取令牌
    var token = HttpContext.Request.Headers["Authorization"].ToString().Replace("Bearer ", "");
    
    // 解析令牌
    var userInfo = JwtTokenHelper.GetToken<JwtTokenModel>(token);
    
    return Ok(userInfo);
}

5. Swagger 集成

// 配置 Swagger
builder.Services.AddSwaggerGen(c =>
{
    c.AddAuthenticationHeader("v1", new OpenApiInfo()
    {
        Title = "My API",
        Description = "",
        Version = "v1"
    });
    SwaggerGenExtensions.IncludeXmlComments(c);
});

// 在中间件中启用 Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.SwaggerUISpanEditable(); // 可选：使 Swagger UI 中的 span 可编辑
});

6. 自定义认证事件

var events = new JwtBearerEvents
{
    OnAuthenticationFailed = context =>
    {
        if (context.Exception.GetType() == typeof(SecurityTokenExpiredException))
        {
            context.Response.Headers.Add("Token-Expired", "true");
        }
        return Task.CompletedTask;
    },
    
    OnChallenge = context =>
    {
        context.HandleResponse();
        context.Response.StatusCode = StatusCodes.Status401Unauthorized;
        context.Response.ContentType = "application/json";
        
        var result = new { Code = 401, Message = "Unauthorized", Result = "" };
        var json = JsonSerializer.Serialize(result);
        
        return context.Response.WriteAsync(json);
    },
    
    OnMessageReceived = context =>
    {
        // 自定义令牌获取逻辑
        if (context.Request.Query.TryGetValue("token", out var token))
        {
            context.Token = token;
        }
        return Task.CompletedTask;
    }
};

// 注册服务时使用自定义事件
builder.Services.AddJWTAuthentications(_jwtConfig, events: events);