MiniAuth

MiniAuth copied to clipboard

Introduction

"One-line code" adds identity management web for your new/old projects

Features

• Compatibility: Based JWT, Cookie, and Session that follow the .NET Identity standard.
• Out of the box: Easy integration, MiniAuth works with APIs, MVC, Razor Pages.
• Multi-platform: Supports Linux, macOS environments.
• Multiple Database Support: Compatible with any database that follow the Identity EF Core standard.

Installation

Install the package from NuGet:

dotnet add package MiniAuth
// or
NuGet\Install-Package MiniAuth

Quick Start

Add a single line of code services.AddMiniAuth() in Startup, then run your project. Example:

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddMiniAuth();

        var app = builder.Build();
        app.Run();
    }
}

The default admin account is [email protected] with the password E7c4f679-f379-42bf-b547-684d456bc37f (remember to change the password). The admin page can be accessed at http(s)://yourhost/miniauth/index.html.

Note: If you already have your own identity auth, please follow the instructions below.

Existing Identity Setup

Turn off autoUse for AddMiniAuth, and replace it with your own IdentityDBContext, user, and permission authentication in UseMiniAuth, placing it after your own Auth. Example:

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    var connectionString = builder.Configuration.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
    builder.Services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(connectionString));
    builder.Services.AddDatabaseDeveloperPageExceptionFilter();

    builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddRoles<IdentityRole>()
        .AddEntityFrameworkStores<ApplicationDbContext>();

    builder.Services.AddControllersWithViews();

    builder.Services.AddMiniAuth(autoUse: false); // <= ❗❗❗

    var app = builder.Build();

    app.UseMiniAuth<ApplicationDbContext, IdentityUser, IdentityRole>();  // <= ❗❗❗ 
    app.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    app.MapRazorPages();

    app.Run();
}

Order Matters

Please place UseMiniAuth after routing generation; otherwise, the system won't be able to obtain routing data for permission checks, like:

app.UseRouting();
app.UseMiniAuth();

Note: Adding Role Rules

Please add AddRoles<IdentityRole>(); otherwise [Authorize(Roles = "YourRole")] won't work.

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddRoles<IdentityRole>() // ❗❗❗ 
    .AddEntityFrameworkStores<ApplicationDbContext>();

Disable MiniAuth Login

If you only want to use your own login logic, page, and API, you can custom the login path and turn off the switch.

// before add service
MiniAuthOptions.LoginPath = "/Identity/Account/Login";
MiniAuthOptions.DisableMiniAuthLogin = true;

Changing Databases

MiniAuth system defaults to using SQLite without any code settings required. If you need to switch, specify a different database type in app.UseMiniAuth.

Configuration and Options

Default Mode

• MiniAuth operates in a default mode where IT Admin centrally manages user operations like registration and password reset, requiring an Admin privilege account to perform these actions. Default Role = miniauth-admin.

Login and User Validation

For non-ApiController, login redirects to the login.html page (determined by Headers["X-Requested-With"] == "XMLHttpRequest" or ApiControllerAttribute). ApiController Controllers do not redirect to the login page by default but return a 401 status code.

Distributed Systems

• Please switch the database source to SQL Server, MySQL, PostgreSQL, etc.

Custom Frontend

• The management backend front-end uses Vue3 + Vite at /src/Frontend_Identity. You can update the miniauth UI after using npm run build.
• If you do not want to use the miniauth default for the login page, you can use the identity scaffolded Login.cshtml in mvc, or change the login.html, js, css of the miniauth frontend.

Release Notes

Refer to the Release Notes for updates.

TODO

Link: MiniAuth.Identify project