Configuration Options

Moka.Auth provides flexible configuration options for customizing authentication, authorization, and user management features. This guide covers all available options and their usage.

Core Service Configuration

Basic Setup

The minimal setup requires calling AddMokaAuth in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Configure database (required before AddMokaAuth)
builder.Services.AddMokaAuthDbContext(dbOptions =>
{
    dbOptions.ConnectionString = "Data Source=moka.db";
    dbOptions.DbType = DbType.SQLite;
    dbOptions.AutoMigrate = true;
});

// Add Moka.Auth services with default configuration
builder.Services.AddMokaAuth();

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

Authentication Configuration

Configure which authentication providers to enable:

builder.Services.AddMokaAuth(options =>
{
    // Enable/disable specific authentication methods
    options.EnableJWT = true;
    options.EnableCookie = true;
    options.EnableApiKey = true;
    options.EnableOpenID = false;

    // Enable user impersonation feature
    options.EnableImpersonation = true;

    // Configure JWT options
    options.JwtOptions = new JwtOptions
    {
        Key = "your-secure-key-min-32-chars-long-for-jwt-auth",
        Issuer = "your-application",
        Audience = "your-api",
        ExpirationMinutes = 30,
        RefreshTokenExpirationDays = 7,
        EnableRefreshTokens = true
    };

    // Configure API Key options
    options.ApiKeyOptions = new ApiKeyOptions
    {
        HeaderName = "X-Api-Key"
    };
});

Endpoint Configuration

Configure which built-in endpoints to enable:

app.MapMokaDefaultEndpoints(options =>
{
    // Base route for all endpoints
    options.RoutePrefix = "/api/auth";

    // Enable/disable endpoint groups
    options.EnableAuthEndpoints = true;      // Login, logout, token refresh
    options.EnableUserEndpoints = true;      // User management
    options.EnableRoleEndpoints = true;      // Role management
    options.EnablePermissionEndpoints = true; // Permission management
    options.EnableApiKeyEndpoints = true;    // API key management
    options.EnableImpersonationEndpoints = true; // User impersonation

    // Authorization requirements
    options.RequireAuthorizationForUserEndpoints = true;
    options.RequireAuthorizationForRoleEndpoints = true;
    options.RequireAuthorizationForPermissionEndpoints = true;
    options.RequireAuthorizationForApiKeyEndpoints = true;
});

JWT Provider Options

The JwtOptions class provides detailed customization for JWT authentication:

options.JwtOptions = new JwtOptions
{
    // Required - secure key for signing (min 32 chars)
    Key = "your-secure-key-min-32-chars-long",

    // Token issuer and audience
    Issuer = "your-application",
    Audience = "your-api",

    // Token expiration
    ExpirationMinutes = 30,

    // Refresh token settings
    EnableRefreshTokens = true,
    RefreshTokenExpirationDays = 7
};

Cookie Authentication Options

Configure cookie-based authentication:

options.CookieOptions = new CookieAuthOptions
{
    // Authentication endpoints
    LoginPath = "/login",
    LogoutPath = "/logout",
    AccessDeniedPath = "/access-denied",

    // Cookie behavior
    SlidingExpiration = true,
    ExpirationMinutes = 30
};

API Key Options

Configure API key authentication:

options.ApiKeyOptions = new ApiKeyOptions
{
    // Request header name that will contain the API key
    HeaderName = "X-Api-Key"
};

OpenID Connect Options

Configure authentication with external identity providers:

options.OpenIDOptions = new OpenIDOptions
{
    // OIDC provider details
    Authority = "https://your-identity-provider",
    ClientId = "your-client-id",
    ClientSecret = "your-client-secret",

    // Authentication flow
    ResponseType = "code",
    GetClaimsFromUserInfoEndpoint = true,

    // Requested scopes
    Scopes = new List<string> { "openid", "profile", "email" }
};

Identity System Options

Configure ASP.NET Core Identity settings:

options.EnableIdentitySystem = true;
options.IdentityOptions = new MokaIdentityOptions
{
    // Password requirements
    Password = new PasswordOptions
    {
        RequireDigit = true,
        RequireLowercase = true,
        RequireUppercase = true,
        RequireNonAlphanumeric = true,
        RequiredLength = 8
    },

    // Lockout settings
    Lockout = new LockoutOptions
    {
        AllowedForNewUsers = true,
        DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15),
        MaxFailedAccessAttempts = 5
    },

    // User requirements
    User = new UserOptions
    {
        RequireUniqueEmail = true
    },

    // Sign-in requirements
    SignIn = new SignInOptions
    {
        RequireConfirmedEmail = false,
        RequireConfirmedAccount = false
    }
};

Advanced: Service Customization

You can replace the default Moka.Auth services with your own implementations:

// Replace default user service with custom implementation
builder.Services.AddScoped<IUserService, CustomUserService>();

// Replace default role service with custom implementation
builder.Services.AddScoped<IRoleService, CustomRoleService>();

// Replace default permission service with custom implementation
builder.Services.AddScoped<IPermissionService, CustomPermissionService>();

Middleware Configuration

Don’t forget to add the appropriate middleware in your application pipeline:

var app = builder.Build();

// Configure the HTTP request pipeline
app.UseHttpsRedirection();

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

// Map the endpoints
app.MapMokaDefaultEndpoints();