Skip to content

Latest commit

 

History

History
369 lines (247 loc) · 12.9 KB

README.md

File metadata and controls

369 lines (247 loc) · 12.9 KB
Raw

NuGet star GitHub stars version

Your Star, Donate, Recomm. can make MiniAuth better

Introduction

"One-line code" adds asp.net core identity user/role management web for your new/old projects

Image 1 Image 2
Image 3 Image 4

Features

  • Compatibility: Supports .NET identity Based on JWT, Cookie, Session, etc.
  • Simple: Plug-and-play design, API, SPA, MVC, Razor Page, etc.
  • Supports multiple databases: Supports Oracle, SQL Server, MySQL, etc. EF Core
  • Non-intrusive: Does not affect existing databases or project structures
  • Multi-platform: Supports Linux, macOS environments

Installation

Install the package from NuGet

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.

Add [Authorize] to categories or methods that require permission management, or role control [Authorize(Roles = "role")], return 401 status if not logged in, and return 403 status if no permission.

MiniAuth Cookie Identity

MiniAuth is preset as a single Coookie Based identity, please change to JWT, etc. Auth for front-end and back-end separation projects.

MiniAuth JWT Identity

Setting AuthenticationType = BearerJwt

builder.Services.AddMiniAuth(options:(options) =>
{
    options.AuthenticationType = MiniAuthOptions.AuthType.BearerJwt;
});

Please remember to set new JWT Security Key, e.g.

builder.Services.AddMiniAuth(options: (options) =>
{
    options.JWTKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("6ee3edbf-488e-4484-9c2c-e3ffa6dcbc09"));
});

Getting token

Frontend Javascript XHR example

var data = JSON.stringify({
  "username": "[email protected]",
  "password": "E7c4f679-f379-42bf-b547-684d456bc37f",
  "remember": false
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});
xhr.open("POST", "http://yourhost/miniauth/login");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);

response

{
    "ok": true,
    "code": 200,
    "message": null,
    "data": {
        "tokenType": "Bearer",
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIxZTIxOGY4My1iZjE3LTRhY2YtODhmOS1iOTQ3NjhjOWUwMGMiLCJuYW1lIjoiYWRtaW5AbWluaS1zb2Z0d2FyZS5naXRodWIuaW8iLCJyb2xlIjoibWluaWF1dGgtYWRtaW4iLCJzdWIiOiJhZG1pbkBtaW5pLXNvZnR3YXJlLmdpdGh1Yi5pbyIsIm5iZiI6MTcxODIwNDg5NSwiZXhwIjoxNzE4MjA1Nzk1LCJpYXQiOjE3MTgyMDQ4OTUsImlzcyI6Ik1pbmlBdXRoIn0._-DQ_rcbeju8_nrK2lD5we0rre04_xdDZNF6NhM0Rg0",
        "expiresIn": 900
    }
}

Save the accessToken in localstorage or a cookie. When calling your [Authorize] API, set the Header Authorization to Bearer + space + accessToken, and the system will automatically verify it.

Example:

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});
xhr.open("GET", "http://yourhost:5014/your/api");
xhr.setRequestHeader("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIxZTIxOGY4My1iZjE3LTRhY2YtODhmOS1iOTQ3NjhjOWUwMGMiLCJuYW1lIjoiYWRtaW5AbWluaS1zb2Z0d2FyZS5naXRodWIuaW8iLCJyb2xlIjoibWluaWF1dGgtYWRtaW4iLCJzdWIiOiJhZG1pbkBtaW5pLXNvZnR3YXJlLmdpdGh1Yi5pbyIsIm5iZiI6MTcxODIwNDg5NSwiZXhwIjoxNzE4MjA1Nzk1LCJpYXQiOjE3MTgyMDQ4OTUsImlzcyI6Ik1pbmlBdXRoIn0._-DQ_rcbeju8_nrK2lD5we0rre04_xdDZNF6NhM0Rg0");
xhr.send();

Set Expiration Time

options.TokenExpiresIn = 30 * 60;

The unit is in seconds, with a default setting of 30 minutes. Additionally, note that .NET JWT ClockSkew in JwtBearerOptions is preset to add an extra 5 minutes reason.

Refresh Token API (JWT)

API : /MiniAuth/refreshToken Body:

{
   "refreshToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxZTIxOGY4My1iZjE3LTRhY2YtODhmOS1iOTQ3NjhjOWUwMGMiLCJuYmYiOjE3MTg1MjIxOTEsImV4cCI6MTcxODUyMzk5MSwiaWF0IjoxNzE4NTIyMTkxLCJpc3MiOiJNaW5pQXV0aCJ9.HYBWrM2suDiM4OG0FSlXhNgktZIG9l3ufmIAnwZiIoU"
}

Header:

Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiYWRtaW5AbWluaS1zb2Z0d2FyZS5naXRodWIuaW8iLCJyb2xlIjoibWluaWF1dGgtYWRtaW4iLCJzdWIiOiIxZTIxOGY4My1iZjE3LTRhY2YtODhmOS1iOTQ3NjhjOWUwMGMiLCJuYmYiOjE3MTg1MjIxOTEsImV4cCI6MTcxODUyNTc5MSwiaWF0IjoxNzE4NTIyMTkxLCJpc3MiOiJNaW5pQXV0aCJ9.rgAgsziAdLqOC9NYra-M9WQl8BJ99sRdfzRKNkMz9dk

The expiration time is set to MiniAuthOptions.TokenExpiresIn / 2, with a default of 30 minutes.

Settings, Options, Customization

Default Mode

  • The default mode of MiniAuth is centralized user management by IT Admins. Operations such as user registration and password reset require an admin account with the predefined role = miniauth-admin.

Disable MiniAuth Login

If you only want to use your own login logic, pages, and APIs, you can specify the login path and disable the MiniAuth login switch.

// Place before service registration 
builder.Services.AddMiniAuth(options: (options) =>
{
    options.LoginPath = "/Identity/Account/Login";
    options.DisableMiniAuthLogin = true;
});

Customize Default SQLite Connection String

builder.Services.AddMiniAuth(options: (options) =>
{
    options.SqliteConnectionString = "Data Source=miniauth_identity.db";
});

Custom Database, Users, and Roles

MiniAuth is designed to work seamlessly with SQLite EF Core, IdentityUser, and IdentityRole by default. If you need to switch, please specify different databases and your own user and role classes using generics in app.UseMiniAuth.

app.UseMiniAuth<YourDbContext, YourIdentityUser, YourIdentityRole>();

Login, User Authentication

For non-ApiController, the default login redirection is to the login.html page (determined by checking if Headers["X-Requested-With"] == "XMLHttpRequest" or the presence of the ApiControllerAttribute). Controllers marked as ApiController do not redirect to a login page by default; instead, they return a 401 status code.

Custom Frontend

  • The admin dashboard frontend is located in /src/Frontend_Identity and primarily uses Vue3 + Vite. Running npm run build will update the miniauth UI.
  • If you don't want to use the default miniauth login page, MVC allows you to use the scaffolded Login.cshtml provided by identity, or you can modify the login.html, js, and css files in the miniauth frontend.

Custom Route Prefix

builder.Services.AddMiniAuth(options: (options) =>
{
    options.RoutePrefix = "YourName";
});

The default RoutePrefix is MiniAuth.

Login API (JWT)

API: /MiniAuth/login

Body:

{
   "username":"[email protected]",
   "password":"E7c4f679-f379-42bf-b547-684d456bc37f",
   "remember":false
}

Response:

{
    "ok": true,
    "code": 200,
    "message": null,
    "data": {
        "tokenType": "Bearer",
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiYWRtaW5AbWluaS1zb2Z0d2FyZS5naXRodWIuaW8iLCJyb2xlIjoibWluaWF1dGgtYWRtaW4iLCJzdWIiOiIxZTIxOGY4My1iZjE3LTRhY2YtODhmOS1iOTQ3NjhjOWUwMGMiLCJuYmYiOjE3MTg1MjIxOTEsImV4cCI6MTcxODUyNTc5MSwiaWF0IjoxNzE4NTIyMTkxLCJpc3MiOiJNaW5pQXV0aCJ9.rgAgsziAdLqOC9NYra-M9WQl8BJ99sRdfzRKNkMz9dk",
        "expiresIn": 3600,
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxZTIxOGY4My1iZjE3LTRhY2YtODhmOS1iOTQ3NjhjOWUwMGMiLCJuYmYiOjE3MTg1MjIxOTEsImV4cCI6MTcxODUyMzk5MSwiaWF0IjoxNzE4NTIyMTkxLCJpc3MiOiJNaW5pQXV0aCJ9.HYBWrM2suDiM4OG0FSlXhNgktZIG9l3ufmIAnwZiIoU"
    }
}

Registration

Please use the built-in registration API and pages provided by ASP.NET Core Identity.

Forgot Password

Please use the built-in forgot password API and pages provided by ASP.NET Core Identity.

Get User Information

Please utilize the built-in APIs and pages provided by ASP.NET Core Identity to retrieve user information. Note that you may need to implement additional logic or endpoints to expose the required user data, depending on your specific application needs. ASP.NET Core Identity provides a robust framework for managing user information, including profile data, roles, and claims.

Notes

Attention to Order

Please place UseMiniAuth after route generation, otherwise, the system cannot obtain routing data for permission checks, as follows:

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

Attention: Please Add Role Rules

Please add AddRoles<IdentityRole>(), otherwise [Authorize(Roles = "permission")] will not take effect.

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

Integrating MiniAuth into an Existing Identity Project with Custom Logic

Disable AddMiniAuth's autoUse, and place UseMiniAuth after your own authentication, replacing the generic parameters with your own IdentityDBContext, user, and permission authentication. Here's an 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();
        }

This allows you to switch between using your own users, roles, database, and Identity logic.

Distributed Systems

  • For database sources, consider switching to databases like SQL Server, MySQL, PostgreSQL, etc.
  • It is recommended to switch to authentication methods like JWT for better integration in a distributed environment.

Release Notes

Refer to the Release Notes for updates.

TODO

Link: MiniAuth.Identify project