Skip to content

Multi-tenancy ​

NetForge ships with always-on multi-tenancy plumbing that stays invisible until you turn it on — single-tenant developers see no "tenant" anywhere. Flip it with one config setting:

jsonc
"Tenancy": { "Mode": "MultiTenant" } // Resolution defaults to UserClaim — see below

Tenant switcher in the top bar

What you get when it's on ​

  • Tenant catalog — /admin/tenants (host admins, tenants.*) lists, creates, and edits tenants; each has a name, status (Active/Suspended), brand colour, and logo. Those three white-label the shell for whoever is in that tenant — including the default one, which is your own product identity, so editing it rebrands the app itself. The default tenant can't be deleted.
  • Per-tenant roles — a user's roles are scoped to a tenant. The same person can be Admin in one tenant and a read-only member in another; permissions re-project the moment they switch. Role definitions are shared; the assignment is per-tenant.
  • Tenant admins — Admin in a customer's tenant runs that tenant: its members, invitations, joining rules, appearance, webhooks, audit log and data. Platform-wide permissions (user accounts, role definitions, app settings, tenants, health, background jobs) only apply in the default tenant, so host administration happens there. From inside another tenant, /admin/tenants opens that tenant's own page and can't reach any other. Nobody can change their own roles.
  • Tenant switcher — a top-bar control lists the tenants you belong to; switching re-tints the app with that tenant's branding and reloads into its data. On a narrow phone it shows just its icon, and on the very narrowest it moves into the account menu.
  • Invitations — invite someone by email to a tenant with a role; they get a signed link to an accept page. Pending invitations can be revoked.
  • Who can join — a tenant is invitation-only until you say otherwise. Its page has two joining rules, each with its own role: people with an email at these domains (staff at @acme.com join as Staff) and anyone (a community or public workspace, with a narrow role). People join when they confirm their email — that's what proves the address — and a domain match beats the open rule. It applies to sign-ups on the tenant's own address (Host/Subdomain/Path/Header resolution). OAuth sign-ups can only use the open rule, and a role that grants every permission can't be handed out this way.
  • Isolation — every tenant-scoped record carries a TenantId and is filtered automatically, so one tenant never sees another's data.

Tenants admin list with per-tenant branding

Switching tenant re-skins the whole shell with that tenant's brand — same app, same account, a different identity over a completely isolated data set:

The Acme tenant — the shell re-tinted with Acme's brand colour

The Globex tenant — a different brand and its own, separate product catalog

Resolution strategies ​

The active tenant always derives from the signed-in user, so a forged host, subdomain, or header can't reach a tenant you don't belong to — a request that names a different tenant from yours is refused. The strategy decides how an unauthenticated request (the sign-in page, its branding) is mapped:

StrategyExampleBest for
UserClaim (default)from the signed-in userone hostname for everyone — most apps
Hostportal.acme.com → acme, via HostMapeach customer on their own domain
Subdomainacme.app.comclassic SaaS
Path/acme/…single-domain hosting
HeaderX-Tenant-IdAPI clients
jsonc
"Tenancy": {
  "Mode": "MultiTenant",
  "Resolution": "Host",
  "HostMap": { "portal.acme.com": "acme", "app.globex.io": "globex" }
}

A request can only name a tenant that exists: an unmapped host, or a subdomain label, path segment, or header that isn't a tenant's id, names none, and the request falls back to the signed-in user's tenant (or the default one). So demo.example.com on a single-tenant-per-host deployment doesn't invent a tenant called demo. Subdomain also checks HostMap first, so most customers can use acme.app.com while a few bring their own domain. The setting is validated at startup — a misspelt strategy, or Host with an empty map, stops the app from booting and says why.

Making a feature tenant-aware ​

Add the ITenantScoped marker to an entity and a global WHERE TenantId = current filter is applied automatically; new rows are stamped with the active tenant on save. That's the whole change — the switcher, invitations, and resolution are already wired. It composes with the normal Add a feature flow: add the marker and the platform does the rest.

Community edition

Multi-tenancy management is a Pro feature; the always-on single-tenant scaffolding stays in every edition. See Editions.

Questions? Discussions · Contact · NetForge Community is MIT-licensed; get Pro with a plan on the configurator.