CellularManagement/docs/JWT-Implementation-Guide.md

# JWT 实现指南

## 1. JwtOptions（配置类）

### 1.1 主要职责
- 存储和管理 JWT 相关的所有配置项
- 提供配置验证功能
- 支持从配置文件加载配置

### 1.2 关键配置项
```csharp
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 关键方法
```csharp
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 关键方法
```csharp
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 关键配置
```csharp
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 选项
```csharp
services.Configure<JwtOptions>(configuration.GetSection(JwtOptions.SectionName));
```

### 2. 注册服务
```csharp
services.AddScoped<IJwtProvider, JwtProvider>();
services.AddScoped<IKeyRotationService, KeyRotationService>();
services.AddSingleton<IConfigureOptions<JwtBearerOptions>, JwtBearerOptionsSetup>();
```

### 3. 使用 JWT 提供者
```csharp
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. **性能考虑**
   - 使用缓存机制
   - 优化令牌验证
   - 控制令牌大小