CellularManagement/docs/JWT-Implementation-Guide.md

JWT 实现指南

1. JwtOptions（配置类）

1.1 主要职责

• 存储和管理 JWT 相关的所有配置项
• 提供配置验证功能
• 支持从配置文件加载配置

1.2 关键配置项

public class JwtOptions
{
    public string SecretKey { get; set; }        // JWT 密钥
    public string Issuer { get; set; }           // 颁发者
    public string Audience { get; set; }         // 受众
    public int ExpiryMinutes { get; set; }       // 访问令牌过期时间
    public int RefreshTokenExpiryDays { get; set; } // 刷新令牌过期时间
    public int ClockSkewMinutes { get; set; }    // 时钟偏差
    public int KeyRotationDays { get; set; }     // 密钥轮换间隔
    public int MinKeyLength { get; set; }        // 密钥最小长度
}

1.3 配置验证

• 验证所有必需字段不为空
• 验证数值字段的有效性
• 验证密钥格式和长度

2. JwtOptionsExtensions（扩展方法类）

2.1 主要职责

• 提供 JwtOptions 的扩展功能
• 实现密钥强度验证
• 提供熵值计算功能

2.2 关键方法

public static class JwtOptionsExtensions
{
    // 验证密钥强度
    public static void ValidateKeyStrength(this JwtOptions options)
    
    // 计算字符串熵值
    private static double CalculateEntropy(string input)
}

2.3 验证标准

• 密钥不能为空
• 密钥必须是有效的 Base64 字符串
• 密钥长度必须满足最小长度要求
• 密钥熵值必须大于 3.5（确保足够的随机性）

3. KeyRotationService（密钥管理服务）

3.1 主要职责

• 管理 JWT 密钥的生命周期
• 实现密钥自动轮换
• 提供密钥生成和验证功能

3.2 关键功能

• 密钥初始化
• 密钥轮换
• 密钥强度验证
• 密钥缓存管理

3.3 安全特性

• 定期自动轮换密钥
• 支持密钥预热
• 防止密钥泄露
• 密钥强度保证

4. JwtProvider（JWT 令牌提供者）

4.1 主要职责

• 生成 JWT 访问令牌和刷新令牌
• 验证 JWT 令牌
• 管理令牌黑名单
• 提供令牌解析功能

4.2 关键方法

public interface IJwtProvider
{
    string GenerateAccessToken(IEnumerable<Claim> claims);
    string GenerateRefreshToken(IEnumerable<Claim> claims);
    bool ValidateToken(string token);
    void RevokeToken(string token);
    void AddToBlacklist(string token);
    IEnumerable<Claim> GetClaimsFromToken(string token);
}

4.3 安全特性

• 令牌撤销机制
• 令牌黑名单
• 完整的令牌验证
• 支持自定义声明

5. JwtBearerOptionsSetup（JWT Bearer 认证配置）

5.1 主要职责

• 配置 ASP.NET Core JWT Bearer 认证
• 设置令牌验证参数
• 配置认证事件处理

5.2 关键配置

public class JwtBearerOptionsSetup : IConfigureOptions<JwtBearerOptions>
{
    public void Configure(JwtBearerOptions options)
    {
        // 配置令牌验证参数
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = _jwtOptions.Issuer,
            ValidateAudience = true,
            ValidAudience = _jwtOptions.Audience,
            ValidateLifetime = true,
            // ... 其他配置
        };
    }
}

5.3 安全特性

• 强制使用 HTTPS
• 完整的令牌验证
• 详细的日志记录
• 异常处理机制

安全最佳实践

1. 密钥管理

   • 使用足够长的随机密钥
   • 定期轮换密钥
   • 使用安全的密钥存储机制

2. 令牌安全

   • 设置合理的过期时间
   • 实现令牌撤销机制
   • 使用令牌黑名单

3. 传输安全

   • 强制使用 HTTPS
   • 验证令牌签名
   • 验证令牌来源

4. 配置安全

   • 验证所有配置项
   • 使用强类型配置
   • 避免硬编码敏感信息

使用示例

1. 配置 JWT 选项

services.Configure<JwtOptions>(configuration.GetSection(JwtOptions.SectionName));

2. 注册服务

services.AddScoped<IJwtProvider, JwtProvider>();
services.AddScoped<IKeyRotationService, KeyRotationService>();
services.AddSingleton<IConfigureOptions<JwtBearerOptions>, JwtBearerOptionsSetup>();

3. 使用 JWT 提供者

public class AuthController : ControllerBase
{
    private readonly IJwtProvider _jwtProvider;

    public AuthController(IJwtProvider jwtProvider)
    {
        _jwtProvider = jwtProvider;
    }

    public IActionResult Login(LoginRequest request)
    {
        // 验证用户
        var claims = GetUserClaims(user);
        var token = _jwtProvider.GenerateAccessToken(claims);
        return Ok(new { token });
    }
}

注意事项

1. 密钥管理

   • 不要在代码中硬编码密钥
   • 使用环境变量或密钥管理服务
   • 定期轮换密钥

2. 令牌配置

   • 设置合理的过期时间
   • 启用所有安全验证
   • 使用 HTTPS

3. 错误处理

   • 实现完整的错误处理
   • 记录详细的日志
   • 返回适当的错误信息

4. 性能考虑

   • 使用缓存机制
   • 优化令牌验证
   • 控制令牌大小