AegisAuthJwt 1.0.7

AegisAuthJwt

JWT 认证库，提供完整的 JWT 令牌认证功能，支持令牌黑名单、自动清理、WebAuthn 双因素认证和数字签名功能。

项目结构

• AegisAuthBase - 核心共享库（实体、仓储接口、服务）
• AegisAuthJwt - JWT 认证库
• AegisAuthSession - Session 认证库
• AegisAuthJwtTest - JWT 测试项目
• AegisAuthSessionTest - Session 测试项目

特性

共同特性

• 🛡️ 密码安全：基于 PBKDF2 的密码哈希（100,000 次迭代）
• 📊 安全审计日志：全面记录认证事件
• 🔒 账户锁定：5 次失败尝试后锁定 30 分钟
• 🌐 ASP.NET Core 集成：无缝集成到 ASP.NET Core 应用
• 🎯 即用控制器：内置控制器可直接使用

AegisAuthJwt 特性

• 🔐 JWT 认证：标准 JWT 令牌认证
• 🚫 令牌黑名单：自动令牌失效机制
• 🔄 令牌刷新：自动续期支持
• 🧹 自动清理：后台清理过期令牌
• 🗝️ 通行密钥集成：JWT + WebAuthn 双因素认证
• ✍️ 数字签名：基于 WebAuthn 的数据签名功能
• 🔒 凭据存储：安全存储 WebAuthn 凭据用于签名验证

AegisAuthSession 特性

• 🔑 Session 认证：基于 Session ID 的认证
• 💾 多种存储：支持内存、Redis、数据库存储
• ⏰ 滑动过期：自动延长活跃 Session
• 🔄 Session 续期：接近过期时自动续期
• 🛡️ Session 固定攻击保护：防止 Session 劫持
• 🧹 后台清理：定期清理过期 Session
• 📱 多设备管理：限制每用户最大 Session 数

快速开始

AegisAuthJwt（JWT 认证）

详细文档请查看：AegisAuthJwt README

安装：

dotnet add package AegisAuthJwt

基础配置：

// 注册仓储
builder.Services.AddScoped<IUserRepository, YourUserRepository>();
builder.Services.AddScoped<ISecurityAuditLogRepository, YourAuditLogRepository>();
builder.Services.AddScoped<ITokenBlacklistRepository, YourTokenBlacklistRepository>();

// 配置 JWT 认证
builder.Services.Configure<AuthSetting>(builder.Configuration.GetSection("AuthSetting"));
builder.Services.AddScoped<AuthManager>();

// 配置 JWT 中间件
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(/* 配置选项 */);

// 可选：配置 WebAuthn 双因素认证
builder.Services.AddScoped<IWebAuthnCredentialRepository, YourWebAuthnCredentialRepository>();
builder.Services.AddFido2(options =>
{
    options.ServerName = "Your App Name";
    options.ServerDomain = "yourdomain.com";
    options.Origins = new HashSet<string> { "https://yourdomain.com" };
});

AegisAuthSession（Session 认证）

详细文档请查看：AegisAuthSession QUICKSTART

安装：

dotnet add package AegisAuthSession

快速配置（三种方式）：

1. 内存存储（开发/测试）

builder.Services.AddScoped<IUserRepository, YourUserRepository>();
builder.Services.AddScoped<ISecurityAuditLogRepository, YourAuditLogRepository>();

builder.Services.AddAegisAuthSessionWithMemory(settings =>
{
    settings.SessionExpirationMinutes = 30;
    settings.MaxSessionsPerUser = 5;
});

app.UseAegisAuthSession();

2. Redis 存储（生产推荐）

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = "localhost:6379";
    options.InstanceName = "AegisAuth:";
});
builder.Services.AddAegisAuthSessionWithRedis();

app.UseAegisAuthSession();

3. 数据库存储

builder.Services.AddDbContext<YourDbContext>(/* 配置 */);
builder.Services.AddScoped<DbContext, YourDbContext>();
builder.Services.AddAegisAuthSessionWithDatabase();

app.UseAegisAuthSession();

认证方式对比

API 端点

两个库都提供了类似的 REST API 端点：

通用端点

AegisAuthJwt 特有端点

AegisAuthSession 特有端点

请求/响应示例

登录请求：

{
  "userName": "testuser",
  "password": "password123"
}

登录响应：

{
  "success": true,
  "data": {
    "userId": "1",
    "userName": "testuser",
    "token": "eyJhbG...", // JWT: token, Session: sessionId
    "refreshToken": "refresh_token", // 仅 JWT
    "role": "Admin"
  },
  "error": null
}

数据模型

核心实体（AegisAuthBase）

User（用户）

public class User
{
    public string Id { get; set; }
    public string UserName { get; set; }
    public string PasswordHash { get; set; }
    public string PasswordSalt { get; set; }
    public string? Role { get; set; }
    public bool IsActive { get; set; }
    public DateTimeOffset? LastLogin { get; set; }
    public int FailedLoginAttempts { get; set; }
    public DateTimeOffset? LockoutEnd { get; set; }
    public DateTimeOffset? PasswordChangedAt { get; set; }
}

SecurityAuditLog（安全审计日志）

public class SecurityAuditLog
{
    public string Id { get; set; }
    public string UserName { get; set; }
    public SecurityEventType EventType { get; set; }
    public string EventDescription { get; set; }
    public SecurityEventResult Result { get; set; }
    public string? Details { get; set; }
    public string? IpAddress { get; set; }
    public string? UserAgent { get; set; }
    public DateTimeOffset CreatedAt { get; set; }
}

JWT 特有实体

TokenBlacklist（令牌黑名单）

public class TokenBlacklist
{
    public string Id { get; set; }
    public string TokenHash { get; set; }
    public int TokenLength { get; set; }
    public DateTime ExpiresAt { get; set; }
    public string? UserId { get; set; }
    public string? UserName { get; set; }
    public string? RevocationReason { get; set; }
    public string? IpAddress { get; set; }
    public string? UserAgent { get; set; }
}

WebAuthnCredential（WebAuthn 凭据）

public class WebAuthnCredential
{
    public string Id { get; set; }
    public string UserId { get; set; }
    public string CredentialId { get; set; }
    public byte[] PublicKey { get; set; }
    public string UserHandle { get; set; }
    public uint SignatureCounter { get; set; }
    public string CredType { get; set; }
    public string RegDate { get; set; }
    public Guid AaGuid { get; set; }
    public string? FriendlyName { get; set; }
}

Session 特有实体

Session（会话）

public class Session
{
    public string Id { get; set; }
    public string UserId { get; set; }
    public string UserName { get; set; }
    public string? Role { get; set; }
    public DateTimeOffset CreatedAt { get; set; }
    public DateTimeOffset ExpiresAt { get; set; }
    public DateTimeOffset LastAccessedAt { get; set; }
    public string? IpAddress { get; set; }
    public string? UserAgent { get; set; }
}

仓储接口

您需要实现以下仓储接口：

所有项目都需要：

• IUserRepository
• ISecurityAuditLogRepository

AegisAuthJwt 额外需要：

• ITokenBlacklistRepository
• IWebAuthnCredentialRepository（用于通行密钥和数字签名功能）

AegisAuthSession 不需要额外仓储（使用 ISessionStore）

安全特性

密码安全

• ✅ PBKDF2 哈希算法
• ✅ 100,000 次迭代
• ✅ 随机盐值
• ✅ SHA256 密码哈希

账户保护

• ✅ 失败登录计数（5 次后锁定）
• ✅ 账户锁定（30 分钟）
• ✅ 密码修改追踪
• ✅ 账户激活状态

WebAuthn 安全

• ✅ FIDO2 标准兼容
• ✅ 公钥认证（私钥不离开客户端）
• ✅ 防重放攻击（唯一挑战）
• ✅ 凭据隔离（按域名）
• ✅ 数字签名验证
• ✅ 客户端私钥加密存储

会话安全（AegisAuthSession）

• ✅ Session 固定攻击保护
• ✅ 滑动过期时间
• ✅ 多设备管理
• ✅ 强制登出所有设备

审计与监控

• ✅ 全面的安全审计日志
• ✅ IP 地址追踪
• ✅ User-Agent 记录
• ✅ 事件类型分类

配置示例

JWT 配置（appsettings.json）

{
  "AuthSetting": {
    "JwtTokenKey": "your-256-bit-secret-key-here-minimum-32-characters",
    "JwtTokenIssuer": "https://yourdomain.com",
    "JwtTokenAudience": "https://yourdomain.com",
    "AccessTokenExpirationMinutes": 60,
    "RefreshTokenExpirationDays": 7
  },
  "TokenCleanupWorker": {
    "Enabled": true,
    "CleanupIntervalHours": 24
  }
}

WebAuthn 配置（appsettings.json）

{
  "WebAuthn": {
    "ServerName": "Your App Name",
    "ServerDomain": "localhost",
    "Origins": ["https://localhost:5001"],
    "Timeout": 60000
  },
  "AuthSetting": {
    "EnableWebAuthn": true,
    "EnablePasskeyRegistration": true,
    "EnableDigitalSignatures": true
  }
}

Session 配置（appsettings.json）

{
  "SessionSetting": {
    "SessionExpirationMinutes": 30,
    "SessionRememberMeExpirationDays": 7,
    "MaxSessionsPerUser": 5,
    "SessionIdLength": 64,
    "SessionCookieName": "AegisAuthSession",
    "EnableSessionFixationProtection": true,
    "EnableSlidingExpiration": true,
    "SessionRenewalMinutes": 10,
    "CleanupIntervalMinutes": 60
  },
  "Redis": {
    "Configuration": "localhost:6379",
    "InstanceName": "AegisAuth:"
  }
}

文档

AegisAuthJwt

• 完整文档

AegisAuthSession

• 快速开始
• 存储实现指南

测试项目

两个测试项目提供了完整的使用示例：

• AegisAuthJwtTest - JWT 认证完整示例
• AegisAuthSessionTest - Session 认证完整示例

运行测试项目：

cd AegisAuthJwtTest
dotnet run

# 或
cd AegisAuthSessionTest
dotnet run

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎贡献！请提交 Pull Request 或创建 Issue。