ZCloakNet 1.2.2

🔐 ZCloakNet – Authentication Library for .NET

ZCloakNet is a powerful and lightweight authentication library for .NET 8+ that integrates seamlessly with Keycloak, providing everything you need for user registration, activation, login, token refresh, password recovery, and email notifications — all in a few lines of code.

🚀 Features

• ✅ Plug-and-play integration with Keycloak using OAuth2/JWT
• 📬 Built-in email templates for account activation, welcome, and password reset
• 🧩 Extensible activation flow using IActivationStore
• ⚙️ Ready-to-use endpoints (/auth/register, /auth/login, /auth/activate, etc.)
• 📁 Minimal configuration and zero boilerplate

📦 Installation

Add the NuGet package to your project:

dotnet add package ZCloakNet.Auth

⚙️ Configuration

Add the following configuration to your appsettings.json:

"ZCloakNet": {
  "Auth": {
    "BaseUrl": "http://localhost:8080",
    "Realm": "myrealm",
    "AdminClientId": "my-api-client",
    "AdminClientSecret": "super-secret-value-123",
    "PublicClientId": "my-app-client"
  },
  "Email": {
    "Host": "smtp.mailserver.com",
    "Port": 587,
    "Username": "no-reply@myapp.com",
    "Password": "email-password-123",
    "From": "no-reply@myapp.com",
    "EnableSsl": true,
    "Templates": {
      "Activation": {
        "Subject": "Activate your MyApp account",
        "BodyFilePath": "Templates/activation.html"
      },
      "Welcome": {
        "Subject": "Welcome to MyApp",
        "BodyFilePath": "Templates/welcome.html"
      },
      "ForgotPassword": {
        "Subject": "Reset your password",
        "BodyFilePath": "Templates/forgot-password.html"
      }
    }
  }
}

📌 Explanation of settings:

🛠️ Setup in Program.cs

To use the library, simply register it in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// 🔧 Register ZCloakNet
builder.Services.AddZCloakNet(builder.Configuration);

// 🧩 Register your activation store implementation
builder.Services.AddScoped<IActivationStore, UserIdentityService>();

var app = builder.Build();

// ⚙️ Enable middleware and endpoints
app.UseZCloakNet();
app.MapZCloakNet();

app.Run();

✅ What each method does:

📄 IActivationStore Interface

The library exposes an interface so you can implement activation logic using your own database and domain model:

public interface IActivationStore
{
    Task SaveAsync(IdentityUser user, CancellationToken ct);
    Task<IdentityUser> FindByActivationCodeAsync(string code, CancellationToken ct);
    Task ActivateAsync(string code, CancellationToken ct);
}

🧑‍💻 Example Implementation

Here’s a simple implementation of IActivationStore using Entity Framework:

public class UserIdentityService : IActivationStore
{
    private readonly UsersDbContext _context;

    public UserIdentityService(UsersDbContext context)
    {
        _context = context;
    }

    public async Task SaveAsync(IdentityUser user, CancellationToken ct)
    {
        await _context.IdentityUsers.AddAsync(user, ct);
        await _context.SaveChangesAsync(ct);
    }

    public async Task<IdentityUser> FindByActivationCodeAsync(string code, CancellationToken ct)
    {
        return await _context.IdentityUsers
            .AsNoTracking()
            .FirstOrDefaultAsync(u => u.ActivationCode == code, ct);
    }

    public async Task ActivateAsync(string code, CancellationToken ct)
    {
        var user = await _context.IdentityUsers.FirstOrDefaultAsync(u => u.ActivationCode == code, ct);
        if (user is null) return;

        user.IsActive = true;
        user.ActivationCode = $"{user.ActivationCode}-activated-{DateTime.UtcNow:yyyyMMddHHmmss}";
        await _context.SaveChangesAsync(ct);
    }
}

🌐 Example Usage in a Controller

[ApiController]
[Route("api/v1/activation")]
public class ActivationController : ControllerBase
{
    private readonly IActivationStore _activationStore;

    public ActivationController(IActivationStore activationStore)
    {
        _activationStore = activationStore;
    }

    [HttpPost("{code}")]
    public async Task<IActionResult> Activate(string code, CancellationToken ct)
    {
        await _activationStore.ActivateAsync(code, ct);
        return Ok(new { message = "Account successfully activated." });
    }
}

🔌 Available Endpoints

Once you call app.MapZCloakNet();, the following endpoints are available automatically:

✅ Quick Start

dotnet add package ZCloakNet.Auth

builder.Services.AddZCloakNet(builder.Configuration);
builder.Services.AddScoped<IActivationStore, UserIdentityService>();

app.UseZCloakNet();
app.MapZCloakNet();

🧑‍💼 Recommended Project Structure

📁 src/
 ┣ 📁 ZCloakNet.Auth/       # NuGet library
 ┣ 📁 MyApp.API/           # Your API project
 ┣ 📁 MyApp.Domain/        # Domain entities and interfaces
 ┣ 📁 MyApp.Infrastructure/# EF Core + database logic
 ┗ 📁 MyApp.Tests/         # Unit tests

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to open an issue or submit a pull request.

📝 License

This project is licensed under the MIT License.