JWTOauth2.Core 2.0.0

JWTOauth2

Reusable OAuth2/JWT authentication package for .NET with access token + refresh token flow.

Projects

• JWTOauth2.Core
  • Token generation and validation logic
  • Contracts: ITokenService, IRefreshTokenStore
• JWTOauth2.AspNetCore
  • ASP.NET Core integration
  • DI extensions: AddJwtOauth2(...), AddJwtOauth2Mfa()
• JWTOauth2.Core.Tests
  • Unit tests for token service behavior

Quick Start

1) Install package (consumer API)

dotnet add package JWTOauth2.AspNetCore

2) Configure services in Program.cs

using JWTOauth2.AspNetCore.Extensions;
using JWTOauth2.Core.Interfaces;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddJwtOauth2(options =>
{
    var auth = builder.Configuration.GetSection("Auth");
    options.Issuer = auth["Issuer"]!;
    options.Audience = auth["Audience"]!;
    options.AccessTokenSecret = auth["AccessTokenSecret"]!;
    options.RefreshTokenSecret = auth["RefreshTokenSecret"]!;
    options.AccessTokenExpiration = TimeSpan.FromMinutes(int.Parse(auth["AccessTokenExpirationMinutes"]!));
    options.RefreshTokenExpiration = TimeSpan.FromDays(int.Parse(auth["RefreshTokenExpirationDays"]!));
});

// Required: your app must implement this.
builder.Services.AddScoped<IRefreshTokenStore, MyRefreshTokenStore>();

// Optional: registers IMfaService for TOTP MFA support.
builder.Services.AddJwtOauth2Mfa();

builder.Services.AddControllers();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

3) Add config to appsettings.json

{
  "Auth": {
    "Issuer": "MyApp",
    "Audience": "MyApp",
    "AccessTokenSecret": "super-secret-access-key-at-least-32-chars!!",
    "RefreshTokenSecret": "super-secret-refresh-key-at-least-32-chars!!",
    "AccessTokenExpirationMinutes": 15,
    "RefreshTokenExpirationDays": 7
  }
}

Core Usage

Inject ITokenService in your auth endpoints/services:

• GenerateTokenPair(...) on login
• ValidateRefreshToken(...) on refresh/logout
• Store/revoke refresh token JTI with your IRefreshTokenStore implementation

MFA (TOTP) Usage

IMfaService is available from JWTOauth2.Core and can be registered in ASP.NET Core with:

builder.Services.AddJwtOauth2Mfa();

Available methods:

• GenerateSecretKey() - creates a Base32 TOTP secret
• GenerateOtpUri(secretKey, userEmail, issuer, period, digits, hashMode) - creates an otpauth:// URI for QR code enrollment
• ValidCode(secretKey, code, hashMode) - verifies the current TOTP code and returns ValidationResult

Typical MFA flow:

1. User enables MFA → generate a secret key once.
2. Build an OTP URI and display it as a QR code in your UI.
3. Ask for one verification code before marking MFA as enabled.
4. During login, after password validation, require TOTP verification.

Protecting the MFA secretKey

The library intentionally returns the raw Base32 secret so you can decide storage strategy. Do not store it in plaintext.

Recommended:

1. Encrypt (protect) before saving to DB.
2. Decrypt (unprotect) only right before ValidCode(...).
3. Keep encryption keys in a proper key store (Azure Key Vault, AWS KMS, GCP KMS, HSM, or ASP.NET Core Data Protection key ring).

Example with ASP.NET Core Data Protection:

public sealed class MfaSecretProtector(IDataProtectionProvider provider)
{
    private readonly IDataProtector _protector = provider.CreateProtector("JWTOauth2.MFA.Secret.v1");

    public string Protect(string plainSecret) => _protector.Protect(plainSecret);
    public string Unprotect(string protectedSecret) => _protector.Unprotect(protectedSecret);
}

When validating:

1. Load encrypted secret from storage.
2. Unprotect it in memory.
3. Call mfaService.ValidCode(unprotectedSecret, code).
4. Discard plaintext immediately after validation.

Build and Test (repo)

dotnet build
dotnet test

Security Notes

• Use different secrets for access and refresh tokens
• Keep secrets out of source code (env vars / secret manager)
• Keep access token lifetime short
• Implement refresh token rotation and reuse detection