VisuAuth 0.2.0

<div align="center">

VisuAuth

The visual admin for ASP.NET Core Identity.

Drop-in admin dashboard, multi-tenancy, and themeable end-user auth pages — without forcing you to rebuild what the framework should ship with.

</div>

🚀 v0.1.0 is live on NuGet. First feature release — admin UI, end-user pages, multi-tenancy, the four theming layers, and the mobile JWT / WebView channel. Install via dotnet add package VisuAuth. Pre-1.0, breaking changes can land on any 0.x bump and will always be flagged in the CHANGELOG.

What it is

VisuAuth fills the gap that ASP.NET Core Identity leaves: it ships a complete admin UI for users/roles/claims, a multi-tenancy layer with per-tenant isolation, and themeable end-user authentication pages — all drop-in via two lines of code, the same way Hangfire ships its dashboard.

// Two-line drop-in — the form recommended for most consumers.
builder.Services.AddVisuAuth<ApplicationUser>();

app.MapVisuAuth();

Need finer control? The same call has a fluent form so you can pick the surfaces you want:

builder.Services.AddVisuAuth()
    .UseAspNetIdentity<ApplicationUser>()
    .AddAdminUi()
    .AddEndUserUi();

Either way, navigate to /visuauth/admin for the dashboard and /visuauth/login for the login page. A complete sample, including the EF Core / Identity wiring this snippet leaves out, lives in samples/Sample.WebApp.

What it gives you

🖥️ Admin UI (/visuauth/admin)

• List, search, filter users with pagination
• Create, edit, lock, unlock, delete users
• Reset password, force logout, reset 2FA
• Manage roles and claims
• Per-tenant scoped views

🌐 End-user UI

• /visuauth/login — email + password
• /visuauth/register — self-service signup (configurable)
• /visuauth/forgot-password & /visuauth/reset-password
• /visuauth/confirm-email
• /visuauth/logout
• /visuauth/two-factor — coming in v0.2
• /visuauth/profile — account self-management, coming in v0.3

🏢 Multi-tenancy

• TenantId column on AspNetUsers (and friends)
• Global query filter applied automatically
• Tenant resolution via HTTP header (X-Tenant-Id) or cookie set by the admin sidebar switcher (subdomain and JWT-claim resolvers planned for v0.2)
• Per-tenant branding via the theming layers below (per-tenant password policy / lockout planned for v0.2)

🎨 Theming

• Layer 1: Override CSS variables — colors, fonts, logo, radius
• Layer 2: Programmatic config via VisuAuthTheme
• Layer 3: Razor view override for granular control
• Layer 4: Per-tenant theme resolved at runtime

📱 Mobile-ready

• REST API at /visuauth/api/auth with JWT (HS256) issuance
• WebView flow with deep-link callback for native apps

🔌 Pluggable backend

• v0.1: ASP.NET Core Identity
• v0.2: Microsoft Entra ID (admin UI via Microsoft Graph)
• v0.3: Microsoft Entra External ID

Abstractions (IUserStore, IRoleStore, IAuthenticationFlow, UserBackendCapabilities) are shaped from day 1 so adapters plug in cleanly.

Why VisuAuth exists

ASP.NET Core Identity gives you UserManager<T>, hashing, lockout, and token providers — but no admin UI, no multi-tenancy, no professional end-user pages. Every team rebuilds the same fragments, badly, under deadline pressure.

VisuAuth is to Identity what Hangfire is to background jobs: it adds the dashboard and operational surface that the framework should have shipped with.

Stack

Roadmap

Repository structure

visuauth/
├── src/
│   ├── VisuAuth/                  # Meta-package
│   ├── VisuAuth.Abstractions/     # IUserStore, capabilities, contracts
│   ├── VisuAuth.Identity/         # ASP.NET Identity adapter
│   ├── VisuAuth.Entra/            # Microsoft Entra ID adapter — see its own README
│   ├── VisuAuth.AdminUi/          # Admin dashboard
│   └── VisuAuth.EndUserUi/        # Login, register, password reset, etc.
├── tests/
├── samples/
│   ├── Sample.WebApp/             # Drop-in example (Identity + Entra toggle)
│   └── Sample.EntraWebApp/        # Minimal Entra-only reference
└── docs/                          # (Docusaurus, coming soon)

Getting started

VisuAuth assumes a project that already has ASP.NET Core Identity + EF Core configured. The reference setup lives in samples/Sample.WebApp; the section below is the quickest path from an empty project to a working /visuauth/admin.

1. Install

dotnet add package VisuAuth

That meta-package pulls in VisuAuth.Abstractions, VisuAuth.Identity, VisuAuth.AdminUi, and VisuAuth.EndUserUi as transitive dependencies. Need only a subset? Install the individual VisuAuth.* packages instead.

2. Identity user, DbContext, migrations

Define an Identity user and the DbContext that owns it. The single-tenant form is fine for v0.1 even if you plan to opt into multi-tenancy later — swap IdentityUser for MultiTenantIdentityUser and IdentityDbContext<TUser> for MultiTenantIdentityDbContext<TUser> when you do.

public sealed class ApplicationUser : IdentityUser { }

public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
    : IdentityDbContext<ApplicationUser>(options);

Run dotnet ef migrations add Initial && dotnet ef database update (or your equivalent) to create the AspNet* tables. VisuAuth does not add tables of its own in v0.1.

3. Wire VisuAuth in Program.cs

using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using VisuAuth;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("Default")));

builder.Services
    .AddIdentity<ApplicationUser, IdentityRole>()
    .AddEntityFrameworkStores<AppDbContext>()
    .AddDefaultTokenProviders();

// Two-line drop-in — registers Identity adapter + admin UI + end-user UI.
builder.Services.AddVisuAuth<ApplicationUser>();

var app = builder.Build();

app.UseStaticFiles();    // serves /_content/VisuAuth.AdminUi/visuauth.css etc.
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapVisuAuth();

app.Run();

4. Try it

• /visuauth/admin — the dashboard. Restrict it with your own authorization policy ([Authorize(Roles = "Admin")] on a custom layout filter, an endpoint convention, etc.) before going to production — VisuAuth does not impose one in v0.1.
• /visuauth/login — the public sign-in page.
• /visuauth/register, /visuauth/forgot-password, /visuauth/reset-password, /visuauth/confirm-email.

For multi-tenancy, mobile JWT issuance, theming (CSS variables, programmatic VisuAuthTheme, view overrides, per-tenant resolvers), and the i18n pipeline, see samples/Sample.WebApp/Program.cs — it exercises every public surface.

Building & packaging

The repo packs five NuGet artefacts in one go: VisuAuth, VisuAuth.Abstractions, VisuAuth.Identity, VisuAuth.AdminUi, VisuAuth.EndUserUi. Every package shares the same version, sourced from a single <VersionPrefix> in Directory.Build.props.

Local build

# Restore, build, test, all at once.
dotnet build src/VisuAuth.slnx --configuration Release
dotnet test  src/VisuAuth.slnx --configuration Release

Local pack (smoke-test a new package without publishing)

# Pre-release with a local marker — never collides with anything on NuGet.org.
dotnet pack src/VisuAuth.slnx \
  --configuration Release \
  --output ./artifacts

# → ./artifacts/VisuAuth.0.1.0-alpha.local.nupkg (and the four sibling packages)

Override the suffix to mimic a CI build locally:

dotnet pack src/VisuAuth.slnx -c Release -o ./artifacts \
  -p:VersionSuffix=alpha.999
# → VisuAuth.0.1.0-alpha.999.nupkg

Override the full version to mimic a stable release:

dotnet pack src/VisuAuth.slnx -c Release -o ./artifacts \
  -p:Version=0.2.0 -p:VersionSuffix=
# → VisuAuth.0.2.0.nupkg

Publish channels

Two release channels run off the same GitHub Actions workflow (.github/workflows/release.yml):

The version comes from Directory.Build.props's <VersionPrefix> plus a suffix computed by the workflow:

• On main: -p:VersionSuffix=alpha.${{ github.run_number }} — monotonic across the repo lifetime, so 0.1.0-alpha.42 < 0.1.0-alpha.43.
• On tag: the tag name (minus the leading v) becomes the full version via -p:Version=....

Both flows run restore → build → test → pack → push. The push step uses dotnet nuget push --skip-duplicate, so a re-run never fails on a package that already exists.

Cutting a stable release

1. Bump <VersionPrefix> in Directory.Build.props if needed (e.g. starting work on 0.2.x).
2. Land the release commit on main.
3. Tag and push:

   git tag v0.2.0
   git push origin v0.2.0
   

4. The Release workflow detects refs/tags/v0.2.0, builds VisuAuth.0.2.0.nupkg (no suffix), and publishes to nuget.org.

Repository secrets

No other secrets are required — source-link metadata and license expression are embedded at build time from Directory.Build.props.

Contributing

Issues, discussions, and PRs welcome. See CONTRIBUTING.md.

License

Apache License 2.0. Copyright © 2026 Thiago Luga and VisuAuth contributors.