Octacer.Web 2.0.0

Octacer.Web

Complete ASP.NET Core admin panel framework with JWT-based Identity API, enum-based role discovery, and comprehensive authentication/authorization features.

Features

🔐 Complete Identity API

• JWT Authentication with access and refresh tokens
• User Registration & Login with comprehensive validation
• Password Management (reset, change, forgot password)
• Token Refresh mechanism for seamless user experience
• User Profile Management with extended properties

🎯 Enum-Based Role Discovery

• Automatic Role Detection from enum definitions across assemblies
• Smart Role Attributes with priority, description, and default settings
• Type-Safe Roles with IntelliSense support
• Multiple Role Sources - define roles per module/department
• Automatic Database Seeding of discovered roles

📚 API Documentation

• Swagger/OpenAPI Integration (API controllers only)
• JWT Authentication in Swagger with Bearer token support
• Comprehensive Endpoint Documentation
• Interactive API Testing

🛡️ Advanced Authorization

• Custom Authorization Attributes for clean API responses
• Role-Based Access Control with enum support
• Policy-Based Authorization ready
• Flexible Permission System

Quick Start

1. Installation

dotnet add package Octacer.Web

2. Define Your Roles

using Octacer.Web.Attributes;

public enum UserRoles
{
    [RoleInfo("Full system administrator", IsDefault = false, Priority = 1)]
    Admin,

    [RoleInfo("Standard customer access", IsDefault = true, Priority = 100)]
    Customer,

    [RoleInfo("Tour guide permissions", IsDefault = false, Priority = 50)]
    Guide
}

3. Configure Services

// Add to Program.cs
builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseSqlServer(connectionString));

builder.Services.AddIdentity<ApplicationUser, ApplicationRole>()
    .AddEntityFrameworkStores<YourDbContext>()
    .AddDefaultTokenProviders();

// Add Octacer Identity API with automatic role discovery
builder.Services.AddOctacerIdentityApi(builder.Configuration);

4. Configure Pipeline

// Configure the HTTP request pipeline
await app.UseOctacerIdentityApiAsync(); // Includes automatic role discovery
app.MapControllers();

5. Add Configuration

{
  "JwtSettings": {
    "SecretKey": "your-super-secret-jwt-key-minimum-32-characters",
    "Issuer": "YourApp",
    "Audience": "YourAppUsers",
    "AccessTokenExpirationMinutes": 15,
    "RefreshTokenExpirationDays": 7
  }
}

API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration
• POST /api/auth/refresh-token - Token refresh
• POST /api/auth/forgot-password - Password reset request
• POST /api/auth/reset-password - Password reset
• POST /api/auth/change-password - Change password
• POST /api/auth/logout - Logout
• GET /api/auth/me - Get current user

Usage Examples

Controller Authorization

[ApiController]
[Route("api/[controller]")]
public class ExampleController : ControllerBase
{
    // Single role
    [HttpGet("admin-only")]
    [Authorize(Roles = nameof(UserRoles.Admin))]
    public IActionResult AdminOnly() => Ok();

    // Multiple roles
    [HttpGet("staff")]
    [Authorize(Roles = $"{nameof(UserRoles.Admin)},{nameof(UserRoles.Manager)}")]
    public IActionResult StaffOnly() => Ok();
}

Role Information

// Get role details
var adminRole = UserRoles.Admin;
var name = adminRole.GetRoleName();           // "Admin"
var description = adminRole.GetRoleDescription(); // "Full system administrator"
var isDefault = adminRole.IsDefaultRole();    // false
var priority = adminRole.GetRolePriority();   // 1

// Get all roles
var allRoles = EnumRoleExtensions.GetAllRoles<UserRoles>();
var defaultRoles = EnumRoleExtensions.GetDefaultRoles<UserRoles>();

Client-Side Usage

// Login request
var loginRequest = new LoginRequest
{
    Email = "user@example.com",
    Password = "SecurePassword123!",
    RememberMe = true
};

var response = await httpClient.PostAsJsonAsync("/api/auth/login", loginRequest);
var authResponse = await response.Content.ReadFromJsonAsync<AuthResponse>();

if (authResponse.Success)
{
    // Store tokens
    var accessToken = authResponse.AccessToken;
    var refreshToken = authResponse.RefreshToken;
    
    // Set authorization header
    httpClient.DefaultRequestHeaders.Authorization = 
        new AuthenticationHeaderValue("Bearer", accessToken);
}

Advanced Features

Custom DbContext Integration

public class YourDbContext : ApplicationDbContext<YourDbContext>, IOctaDatabase
{
    public YourDbContext(DbContextOptions<YourDbContext> options) : base(options) { }
    
    public DbSet<ApplicationUserProperty> UserProperties { get; set; }
    
    // Your custom DbSets
    public DbSet<YourEntity> YourEntities { get; set; }
}

Database Service Usage

public class YourService
{
    private readonly DatabaseService<YourDbContext> _databaseService;
    
    public YourService(DatabaseService<YourDbContext> databaseService)
    {
        _databaseService = databaseService;
    }
    
    public async Task<List<ApplicationUserProperty>> GetUserPropertiesAsync(string userId)
    {
        return await _databaseService.GetUserPropertiesAsync(userId);
    }
}

Multiple Role Enums

// Department-specific roles
public enum SalesRoles
{
    [RoleInfo("Sales representative", Priority = 50)]
    SalesRep,
    
    [RoleInfo("Sales manager", Priority = 20)]
    SalesManager
}

// Module-specific roles
public enum BookingRoles
{
    [RoleInfo("Can view bookings", Priority = 80)]
    BookingViewer,
    
    [RoleInfo("Can manage bookings", Priority = 30)]
    BookingManager
}

Dependencies

This package requires:

• .NET 9.0+
• ASP.NET Core Identity
• Entity Framework Core
• Octacer.Generics

Documentation

• Swagger UI: Available at /swagger when running in development
• API Documentation: Interactive documentation with JWT authentication support
• Role Discovery: Automatic scanning and database seeding

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Support

For support and questions, please open an issue on the GitHub repository.

• Responsive dashboard layout
• ASP.NET Identity integration with role management
• Configuration panels and customizable themes
• Tag helpers for common UI components
• Pluggable file storage (local file system or Google Drive)
• Gmail based email sender service
• Simple integration with existing projects

Installation

dotnet add package Octacer.Web

Setup

Add the library services in Program.cs:

builder.Services.AddOctacerWeb<ApplicationDbContext>(options =>
{
    options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection");

    options.StorageSettings = new GoogleDriveJsonFileSettings
    {
        FilePath = builder.Configuration["Google:CredentialsPath"],
        RootFolderId = builder.Configuration["Google:RootFolderId"]
    };

    options.EmailSender = new EmailSenderService();
    options.Sidebar = new CustomSidebar();
    options.MasterAdmin = new SeedUserData
    {
        email = "admin@example.com",
        password = "StrongPassword123!",
        name = "Administrator",
        role = "Admin"
    };
});

app.UseOctacerWeb<ApplicationDbContext>();

Configuring Email

EmailSenderService uses the Gmail API. Create a Google Cloud service account with Gmail access and download the JSON credentials file. Update HelperServices/GoogleBase.cs with your service account email and private key path or implement your own IEmailSender and set options.EmailSender.

Google Drive Storage

To store files on Google Drive supply a GoogleDriveJsonFileSettings object as shown above. The service account used must have access to the target Drive folder.

Example Usage

Once configured, navigate to /admin to access the dashboard. Files uploaded through the panel will be stored using the selected storage provider.

Requirements

• .NET 9.0 or higher
• ASP.NET Core

License

MIT