Skip to content

Getting started

This guide takes you from an empty project to a working /visuauth/admin in four steps. It assumes you are comfortable with ASP.NET Core and EF Core.

Prerequisites

  • .NET 10 SDK or later.
  • A project that uses (or will use) ASP.NET Core Identity with EF Core — SQL Server, PostgreSQL, or SQLite all work.
  • app.UseStaticFiles() in the pipeline (almost every app already has it) — VisuAuth ships its CSS and the embedded htmx asset as static web assets.

A complete reference consumer lives in samples/Sample.WebApp; it exercises every public surface.

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. Define an Identity user, DbContext, and migrations

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

public sealed class ApplicationUser : IdentityUser { }

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

Create the AspNet* tables:

dotnet ef migrations add Initial
dotnet ef database update

VisuAuth adds no tables of its own for the core admin / end-user surfaces. Optional plugins are explicit and documented — for example the audit-log plugin creates a VisuAuthAuditLog table only when you enable it.

3. Wire VisuAuth in Program.cs

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

var builder = WebApplication.CreateBuilder(args);

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

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

// The drop-in: registers the Identity adapter + admin UI + end-user UI.
builder.Services.AddVisuAuth<ApplicationUser>();

// The end-user sign-in pages and the mobile API issue JWTs, so register an
// issuer. HS256 — the signing key must be at least 32 UTF-8 bytes. Load it
// from configuration or a secret store; never hard-code it.
builder.Services.AddVisuAuthJwt<ApplicationUser>(options =>
{
    options.SigningKey = builder.Configuration["VisuAuth:Jwt:SigningKey"]!;
});

var app = builder.Build();

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

app.Run();

AddVisuAuth<ApplicationUser>() is the drop-in; AddVisuAuthJwt<ApplicationUser>() wires the JWT issuer the end-user pages and the mobile API depend on. No Node.js, no build step, no Razor file copying, no manual middleware wiring.

Why the JWT issuer is required. Even the web sign-in page mints a JWT (for the WebView / mobile return flow), so it resolves IJwtIssuer from DI. Without AddVisuAuthJwt, /visuauth/login and the /visuauth/api/auth/* endpoints fail at runtime. The admin dashboard alone does not need it.

The snippet above reads a Default connection string and a JWT signing key — add both to appsettings.json (SQLite shown; swap the provider to match your database). The signing key is your secret: VisuAuth does not bind it for you, so in production load it from user-secrets / environment / a vault rather than committing it:

{
  "ConnectionStrings": {
    "Default": "Data Source=app.db"
  },
  "VisuAuth": {
    "Jwt": {
      "SigningKey": "change-me-to-a-32-byte-or-longer-random-secret"
    }
  }
}

Prefer finer control?

AddVisuAuth<TUser>() is the recommended shorthand. The same registration has a fluent form so you can pick exactly the surfaces you want:

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

4. Try it

Run the app and open:

  • /visuauth/admin — the dashboard.
  • /visuauth/login — the public sign-in page.
  • /visuauth/register, /visuauth/forgot-password, /visuauth/reset-password, /visuauth/confirm-email.

VisuAuth end-user sign-in page

VisuAuth self-service registration page

The end-user pages ship with the niceties you'd otherwise build by hand — a show/hide password toggle and a built-in language switcher (pt-BR / en):

Show / hide password toggle

Switching the UI language

The admin dashboard is protected by default. Every page under /visuauth/admin requires an authenticated user. That is secure, but usually looser than you want — every signed-in end user qualifies. Restrict it to a role in one line:

builder.Services.AddVisuAuth<ApplicationUser>(admin => admin.RequireRole("Admin"));

The same argument works on the fluent form (.AddAdminUi(admin => admin.RequireRole("Admin"))). For anything beyond roles — claims, custom requirements — use admin.ConfigurePolicy(...):

.AddAdminUi(admin => admin.ConfigurePolicy(p =>
    p.RequireAuthenticatedUser().RequireClaim("department", "it")))

Registering an authorization policy named VisuAuthAdminUiServiceCollectionExtensions.AdminAuthorizationPolicy yourself also works and takes precedence over both.

If the dashboard is already fenced off some other way (an upstream gateway, network isolation), call builder.Services.AllowAnonymousVisuAuthAdmin() to drop the built-in gate.

VisuAuth refuses to start if the admin requires an authenticated user but your app registers no authentication scheme — otherwise the mistake would only surface as a 500 on the first admin request in production. ASP.NET Core Identity registers one for you; for Microsoft Entra ID add VisuAuth.Entra.Web.

Where to next

You want to… Read
Understand the contracts adapters implement Backend abstraction & capabilities
Serve multiple tenants from one app Multi-tenancy
Re-brand the UI (colors, logo, full view overrides) Theming
Issue JWTs for a mobile app, or use the WebView flow Mobile & JWT
Put the admin UI in front of Microsoft Entra ID Microsoft Entra ID adapter
Understand the security model and threat coverage Security posture