AspNetCoreAuthKit 1.0.0

AspNetCoreAuthKit

A zero-friction authentication & authorization toolkit for ASP.NET Core with JWT Bearer, API Key, Refresh Tokens with rotation, and dynamic claim policies — all wired up with a single fluent call.

Why AspNetCoreAuthKit? Every ASP.NET Core project ends up writing the same boilerplate: JWT configuration, API Key middleware, refresh token logic, claim-based policies. AspNetCoreAuthKit wraps all of this into a clean, testable, opt-in abstraction.

✨ Features

• 🔐 JWT Bearer — generate, validate and refresh tokens with one method call
• 🔑 API Key — header or query string, static list or custom async validator
• ♻️ Refresh Tokens — token rotation, revoke single device or all devices
• 🛡️ Dynamic claim policies — [RequireClaim("role", "admin")] without manual registration
• 📋 Common policies — AdminOnly, AuthenticatedUser, ApiKeyOrJwt out of the box
• 🔀 Multi-scheme — JWT and API Key in parallel on the same app
• 🧩 Extensible — plug in your own IRefreshTokenStore (Redis, EF Core, etc.)
• 🧪 DI-ready — every module is opt-in, nothing is registered unless you ask

📋 Requirements

🚀 Installation

dotnet add package AspNetCoreAuthKit

🎯 Quick Start

1. Register services

// Program.cs
builder.Services.AddAuthKit(opt => opt
    .UseJwt(jwt =>
    {
        jwt.SecretKey         = builder.Configuration["Auth:SecretKey"]!;
        jwt.Issuer            = "myapp";
        jwt.Audience          = "myapp-users";
        jwt.AccessTokenExpiry = TimeSpan.FromMinutes(15);
    })
    .UseApiKey(key =>
    {
        key.HeaderName = "X-Api-Key";
        key.ValidKeys  = builder.Configuration
            .GetSection("Auth:ApiKeys").Get<string[]>()!;
    })
    .UseRefreshTokens()
    .UseAuthorization()
);

app.UseAuthentication();
app.UseAuthorization();

2. Generate a token at login

app.MapPost("/auth/login", async (LoginRequest req,
    IJwtTokenService tokenService,
    IRefreshTokenStore store) =>
{
    // validate credentials...

    var result = tokenService.GenerateToken(new TokenRequest
    {
        Subject = user.Id,
        Claims  = [new Claim("role", user.Role)]
    });

    await store.SaveAsync(result.RefreshToken, new RefreshTokenEntry
    {
        Subject   = user.Id,
        ExpiresAt = DateTimeOffset.UtcNow.AddDays(7)
    });

    return Results.Ok(result);
    // { accessToken, refreshToken, expiresAt }
});

3. Refresh a token

app.MapPost("/auth/refresh", async (RefreshRequest req,
    IRefreshTokenService refreshService) =>
{
    try
    {
        var result = await refreshService.RefreshAsync(
            req.AccessToken,
            req.RefreshToken);
        return Results.Ok(result);
    }
    catch (RefreshTokenException)
    {
        return Results.Unauthorized();
    }
});

4. Protect endpoints with policies

// Built-in policies
app.MapDelete("/users/{id}", ...).RequireAuthorization(CommonPolicies.AdminOnly);
app.MapGet("/dashboard", ...).RequireAuthorization(CommonPolicies.ApiKeyOrJwt);

// Declarative claim attribute — no manual policy registration needed
[RequireClaim("role", "admin")]
public IActionResult DeleteUser(int id) => Ok();

// Multiple accepted values (OR logic)
[RequireClaim("role", "admin", "moderator")]
public IActionResult BanUser(int id) => Ok();

📝 Refresh Tokens

AspNetCoreAuthKit implements token rotation by default: every refresh invalidates the old token and issues a new pair.

Custom store (Redis, EF Core, etc.)

public class RedisRefreshTokenStore : IRefreshTokenStore { ... }

.UseRefreshTokens(rt =>
{
    rt.CustomStore = typeof(RedisRefreshTokenStore);
})

📚 API Reference

IJwtTokenService methods

TokenRequest properties

CommonPolicies constants

⚙️ Configuration Reference

JwtAuthOptions

ApiKeyOptions

AuthKitAuthorizationOptions

🧪 Testing

IJwtTokenService and IRefreshTokenStore are plain interfaces — mock them directly in unit tests:

var tokenServiceMock = new Mock<IJwtTokenService>();

tokenServiceMock
    .Setup(s => s.GenerateToken(It.IsAny<TokenRequest>()))
    .Returns(new TokenResult
    {
        AccessToken  = "mocked.jwt.token",
        RefreshToken = "mocked-refresh-token",
        ExpiresAt    = DateTimeOffset.UtcNow.AddMinutes(15)
    });

❤️ Support

If you find AspNetCoreAuthKit useful, consider sponsoring its development.

📄 License

MIT — see LICENSE for details.