Bitzsoft.Integrations.MFA 1.0.0-alpha.7

Bitzsoft.Integrations.MFA

企业级多因素认证（MFA）集成包 — TOTP、Email/SMS 验证码、FIDO2/WebAuthn、恢复码、策略引擎、受信设备、审计日志。

功能特性

• TOTP 时间密码：基于 Otp.NET 的 TOTP 生成/验证，QR 码一键扫描
• Email/SMS 验证码：通过 Provider 抽象接入任意邮件/短信服务商
• FIDO2/WebAuthn：硬件密钥注册/验证，克隆检测，最后一凭据降级保护
• 恢复码：HMAC-SHA256 单向哈希存储，一次性使用后自动消耗
• 策略引擎：用户级 > 角色级 > 全局级三级策略，缓存加速
• 受信设备：服务端生成 GUID 令牌，通过 HttpOnly Cookie 管理
• 审计日志：标准分页查询，记录所有 MFA 操作
• 统一门面：IMfaCoordinator 一键接入策略 + 验证 + 日志

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.MFA

PackageReference

<PackageReference Include="Bitzsoft.Integrations.MFA" Version="1.0.0" />

配置

appsettings.json

{
  "MFA": {
    "Enabled": true,
    "TotpIssuer": "MyApp",
    "TotpStepSeconds": 30,
    "TotpDigits": 6,
    "EmailCodeExpirationMinutes": 5,
    "SmsCodeExpirationMinutes": 5,
    "EnableFido2": true,
    "Fido2RpId": "example.com",
    "Fido2RpName": "My App",
    "MaxFailedAttempts": 5,
    "LockoutMinutes": 15,
    "TrustedDeviceDays": 30,
    "AesKey": "base64-encoded-256-bit-key",
    "RecoveryCodeHashKey": "base64-encoded-256-bit-key"
  }
}

注册服务

核心注册（必选）

using Bitzsoft.Integrations.MFA.DependencyInjection;

services.AddBitzsoftMFA(options =>
{
    options.Enabled = true;
    options.TotpIssuer = "MyApp";
    options.Fido2RpId = "example.com";
    options.AesKey = "your-base64-encoded-256-bit-key";
    options.RecoveryCodeHashKey = "your-base64-encoded-256-bit-key";
});

// 或从 IConfiguration 绑定
services.AddBitzsoftMFA(configuration.GetSection("MFA").Bind);

注册 Provider（必选）

services.AddBitzsoftMFA(options => { /* ... */ })
    .WithCacheProvider<RedisCacheProvider>()
    .WithSmsProvider<AliyunSmsProvider>()
    .WithEmailProvider<SmtpEmailProvider>();

注册 Repository（必选）

services.AddScoped<IUserMfaConfigRepository, SqlUserMfaConfigRepository>();
services.AddScoped<IMfaPolicyRepository, SqlMfaPolicyRepository>();
services.AddScoped<IFido2CredentialRepository, SqlFido2CredentialRepository>();
services.AddScoped<ITrustedDeviceRepository, SqlTrustedDeviceRepository>();
services.AddScoped<IMfaLogRepository, SqlMfaLogRepository>();

使用示例

TOTP 设置

public class MfaController : ControllerBase
{
    private readonly ITotpService _totpService;

    [HttpPost("setup")]
    public async Task<IActionResult> SetupTotp(string userId, string email)
    {
        var setup = _totpService.GenerateSetup(userId, email);
        // 将 setup.QrCodeImage 返回给前端显示 QR 码
        // 将 setup.SecretKey 和 setup.RecoveryCodes 临时存储
        return Ok(new { qrCode = Convert.ToBase64String(setup.QrCodeImage), recoveryCodes = setup.RecoveryCodes });
    }

    [HttpPost("complete-setup")]
    public async Task<IActionResult> CompleteSetup(string userId, string code, string secret, List<string> recoveryCodes)
    {
        await _totpService.CompleteSetupAsync(userId, code, secret, recoveryCodes);
        return Ok();
    }
}

统一验证（推荐通过 IMfaCoordinator）

public class MfaController : ControllerBase
{
    private readonly IMfaCoordinator _coordinator;

    [HttpPost("verify")]
    public async Task<IActionResult> Verify(string userId, string code, MFAType mfaType)
    {
        var context = new MFAVerificationContext
        {
            TenantId = "tenant-1",
            ClientIP = HttpContext.Connection.RemoteIpAddress?.ToString(),
            UserAgent = Request.Headers.UserAgent
        };

        var result = await _coordinator.VerifyAsync(userId, code, mfaType, context);

        if (result.IsLocked)
            return StatusCode(423, new { lockedUntil = result.LockedUntil });

        if (!result.IsSuccess)
            return Unauthorized(new { reason = result.FailReason });

        return Ok(new { remainingCodes = result.RemainingRecoveryCodes });
    }

    [HttpGet("check")]
    public async Task<IActionResult> CheckRequired(string userId, [FromCookie] string? deviceToken)
    {
        var policy = await _coordinator.CheckMfaRequiredAsync(userId, deviceToken);
        return Ok(new { requiresMFA = policy.RequiresMFA, allowedMethods = policy.AllowedMethods });
    }
}

受信设备

[HttpPost("trust-device")]
public async Task<IActionResult> TrustDevice(string userId)
{
    var deviceToken = await _trustedDeviceService.TrustDeviceAsync(
        userId,
        deviceName: Request.Headers.UserAgent,
        clientIP: HttpContext.Connection.RemoteIpAddress?.ToString());

    Response.Cookies.Append("mfa_device_token", deviceToken, new CookieOptions
    {
        HttpOnly = true,
        Secure = true,
        SameSite = SameSiteMode.Strict,
        Expires = DateTimeOffset.UtcNow.AddDays(30)
    });

    return Ok();
}

核心类型一览

依赖

• Microsoft.Extensions.Http — IHttpClientFactory
• Microsoft.Extensions.Options — 选项模式
• Microsoft.Extensions.Logging.Abstractions — 日志抽象
• Otp.NET — TOTP 算法实现
• QRCoder — QR 码生成
• Fido2 — FIDO2/WebAuthn 协议实现

相关包

• Bitzsoft.Integrations.AzureAD -- Azure AD / Microsoft Entra ID 集成
• Bitzsoft.Integrations.Ldap -- LDAP 目录服务集成
• Bitzsoft.Integrations.Sms -- 短信服务集成（SMS OTP 通道）