Quick Start

Basic Setup

This guide will help you quickly set up Moka.Auth in your ASP.NET Core application.

1. Install the Package

dotnet add package Moka.Auth

2. Configure Services

using Moka.Auth.Core.Extensions;
using Moka.Auth.Data.Extensions;
using Moka.Auth.Data.Context;

var builder = WebApplication.CreateBuilder(args);

// Configure database context
builder.Services.AddMokaAuthDbContext(dbOptions =>
{
    // SQLite configuration example
    dbOptions.ConnectionString = "Data Source=moka.db";
    dbOptions.DbType = DbType.SQLite;
    dbOptions.AutoMigrate = true;

    // For SQL Server, use:
    // dbOptions.ConnectionString = "Server=localhost;Database=MokaAuth;Trusted_Connection=True;";
    // dbOptions.DbType = DbType.SqlServer;
});

// Add Moka.Auth with JWT authentication
builder.Services.AddMokaAuth(options => {
    options.UseJwtAuthentication(jwt => {
        // Configure JWT settings if needed
        jwt.SecretKey = "your-secure-key-at-least-32-characters-long";
        jwt.Issuer = "your-application";
        jwt.Audience = "your-clients";
        jwt.ExpirationMinutes = 60;
    });

    // Enable additional features as needed
    options.EnableApiKey = true;
});

// Add authorization
builder.Services.AddMokaAuthorization();

3. Configure Application

var app = builder.Build();

// Apply database migrations and setup
app.UseMokaAuthDatabase();

// Add Moka.Auth middleware
app.UseMokaAuth(builder.Configuration);

// Map default authentication endpoints
app.MapMokaDefaultEndpoints(options =>
{
    options.EnableAuthEndpoints = true;
    options.EnableUserEndpoints = true;
    options.EnableRoleEndpoints = true;
    options.EnablePermissionEndpoints = true;
    options.EnableApiKeyEndpoints = true;
});

app.Run();

Minimal API Usage

Moka.Auth works seamlessly with ASP.NET Core’s minimal API approach. Here’s how to secure your endpoints:

// Unprotected endpoint
app.MapGet("/api/public", () =>
{
    return Results.Ok(new { message = "This is a public endpoint" });
})
.WithName("GetPublicData")
.WithOpenApi();

// Protected endpoint requiring authentication
app.MapGet("/api/protected", (ClaimsPrincipal user) =>
{
    var userId = user.GetUserId(); // Moka.Auth extension method
    return Results.Ok(new { message = $"Hello, user {userId}" });
})
.RequireAuthorization() // This applies the [Authorize] attribute equivalent
.WithName("GetProtectedData")
.WithOpenApi();

// Protected endpoint requiring a specific role
app.MapGet("/api/admin", () =>
{
    return Results.Ok(new { message = "Hello, Admin!" });
})
.RequireAuthorization(policy => policy.RequireRole("Admin"))
.WithName("GetAdminData")
.WithOpenApi();

// Protected endpoint requiring a specific permission
app.MapGet("/api/users/manage", () =>
{
    return Results.Ok(new { message = "User management zone" });
})
.RequireAuthorization(policy => policy.RequirePermission("Users:Manage"))
.WithName("ManageUsers")
.WithOpenApi();

Controller-Based Usage

For controller-based APIs, you can use the standard authorization attributes:

[Authorize]
public class UserController : ControllerBase
{
    private readonly IUserService _userService;

    public UserController(IUserService userService)
    {
        _userService = userService;
    }

    [HttpGet("profile")]
    public async Task<IActionResult> GetProfile()
    {
        // Access authenticated user ID
        var userId = User.GetUserId();
        var user = await _userService.FindByIdAsync(userId);

        return Ok(new {
            Id = user.Id,
            Username = user.UserName,
            Email = user.Email
        });
    }

    [HttpGet("admin-only")]
    [Authorize(Roles = "Admin")]
    public IActionResult AdminOnly()
    {
        return Ok(new { message = "Admin access granted" });
    }
}