Skip to content

Multi-tenancy

VisuAuth serves multiple tenants from a single app and database using a shared-database, shared-schema model: a TenantId column on the user entity, an EF Core global query filter on that entity that scopes its queries to the current tenant, and a SaveChanges interceptor that stamps TenantId on insert for any tenant-scoped entity.

Multi-tenancy is opt-in. Without it, ITenantContext.IsMultiTenancyEnabled is false, the query filters are no-ops, and the tenant catalogue page doesn't render — single-tenant apps pay nothing.

The tenant catalogue admin page

Enabling it

Three things change versus the single-tenant quickstart:

1. Derive your user and DbContext from the multi-tenant base types.

// IdentityUser + IMultiTenantEntity (adds the nullable TenantId column).
public sealed class ApplicationUser : MultiTenantIdentityUser { }

// Applies the global query filter + receives the current tenant context.
public sealed class AppDbContext(
    DbContextOptions<AppDbContext> options,
    ITenantContext tenantContext)
    : MultiTenantIdentityDbContext<ApplicationUser>(options, tenantContext);

2. Opt in when registering VisuAuth, and add the interceptor to the DbContext.

builder.Services.AddVisuAuth()
    .UseAspNetIdentity<ApplicationUser>()
    // The generic overload also wires the tenant catalogue store at
    // /visuauth/admin/tenants.
    .EnableMultiTenant<AppDbContext, ApplicationUser>(options =>
    {
        options.HeaderName = "X-Tenant-Id";   // default
        options.CookieName = "va-tenant";     // default
    })
    .AddAdminUi()
    .AddEndUserUi();

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    options.UseSqlite(builder.Configuration.GetConnectionString("Default"));
    // Stamps TenantId on insert. No-op in single-tenant mode.
    options.AddVisuAuthTenancy(sp);
});

3. Mount the resolver middleware before MapVisuAuth.

app.UseVisuAuthTenancy();   // resolves the tenant for each request
app.MapVisuAuth();

Resolving the current tenant

The resolver middleware sets the tenant for each request from TenantOptions, in this precedence:

  1. The tenant_id claim of a valid bearer token — authoritative. The claim is signed, so for a token-authenticated caller the header and cookie are ignored entirely; a mobile / API client cannot leave its own tenant by sending X-Tenant-Id. A valid token that carries no tenant resolves to no tenant rather than falling back to the header.
  2. HTTP header (UseHeader, default on) — X-Tenant-Id by default. Applies only to callers without a valid bearer token.
  3. Cookie (UseCookie, default on) — va-tenant by default. Set by the admin sidebar tenant switcher for browser flows.

Why the claim wins. The header is client-controlled and unauthenticated; the claim is inside a signed token. Trusting the header for an authenticated API caller would let a user of tenant acme operate in globex simply by setting a request header. See the security posture.

Operators may switch tenants. The admin dashboard signs in with the Identity cookie, whose principal carries no tenant_id claim, so it falls through to the cookie switcher and can reach any tenant — by design. The dashboard itself is gated by the VisuAuth.Admin policy; tighten that policy if your operators should not see every tenant.

Planned. Subdomain resolution (UseSubdomain) is reserved in TenantOptions but not yet wired.

Set RequireTenant = true to reject requests with no resolvable tenant (HTTP 400); leave it false (default) to let global / admin paths run with CurrentTenantId = null.

Anywhere in your app, inspect the ambient tenant via ITenantContext:

public sealed class MyService(ITenantContext tenant)
{
    public void Work()
    {
        if (tenant.IsMultiTenancyEnabled)
        {
            var id = tenant.CurrentTenantId;             // e.g. "acme"
            var name = tenant.CurrentTenantDisplayName;  // when available
        }
    }
}

How isolation works

  • IMultiTenantEntity (a string? TenantId marker) is implemented by MultiTenantIdentityUser. Any entity that implements it is auto-stamped on insert by the interceptor below.
  • Global query filter (reads) — MultiTenantIdentityDbContext<TUser> adds an EF Core query filter on the user entity (TUser), so user queries are automatically restricted to ITenantContext.CurrentTenantId (and span all tenants when tenancy is off or no tenant is resolved). You never write Where(u => u.TenantId == …) by hand for users. To tenant-scope reads of your own additional entities, add your own HasQueryFilter for them.
  • TenantSaveChangesInterceptor (writes) — auto-populates TenantId on insert for every IMultiTenantEntity (leaving rows that already carry one alone), so new rows land in the current tenant without app code remembering to set it.

Because user isolation lives in the query filter and write-stamping lives in the interceptor, the rest of VisuAuth (the stores, the admin UI, the end-user pages) is tenant-agnostic — it just sees the already-scoped users.

The tenant catalogue

The generic EnableMultiTenant<TDbContext, TUser> overload registers ITenantStore, backed by a VisuAuthTenants table, and surfaces the catalogue at /visuauth/admin/tenants — create, rename, and delete tenants inline. The admin sidebar's tenant switcher writes the va-tenant cookie so an operator can scope the dashboard to one tenant at a time.

Switching tenants from the sidebar — the dashboard re-scopes and the per-tenant brand changes

Per-tenant configuration & branding

Once tenancy is on, VisuAuth can vary configuration and appearance per tenant:

  • Branding / theming — implement ITenantThemeResolver (colors, logo) and ITenantViewOverrideResolver (per-tenant Razor templates). See Theming (layer 4).
  • Policy — per-tenant password policy and lockout are resolved through the tenant settings layer.

Adapters. Multi-tenancy as described here is the ASP.NET Core Identity story. For Microsoft Entra adapters the directory itself is the tenant, so this per-user TenantId model does not apply — see the adapter pages.