Skip to content

Implementing SaaS with multitenancy

This guide summarizes how multitenancy fits the ConnectSoft SaaS template program and where to read authoritative architecture.

What “tenant” means here

  • A tenant is an isolation boundary for customers (organization, workspace, or account) in a multi-tenant SaaS product.
  • Editions and entitlements (product catalog and entitlements bounded contexts) determine what a tenant may use; tenants bounded context owns who exists and how they are isolated.

Where templates implement tenancy

  • Backend: Microservices generated from ConnectSoft.Saas.*Template repositories carry tenant-aware application logic; cross-cutting resolution (claims, headers, correlation) is centralized in ConnectSoft.Extensions.Saas.AspNetCore once published (ConnectSoft.Extensions.Saas.* libraries).
  • Front: ConnectSoft.Blazor.Shell.Saas applies tenant/edition policies, hosts MFEs, and coordinates BFF / gateway calls—see ConnectSoft Blazor Templates HLD and SaaS platform — solution plan.
  • APIs: External consumers use ServiceModel packages only; they do not reference domain layers.

DedicatedSingleTenant and appsettings

For single-tenant appliance or on-prem installs, bind Multitenancy via Microsoft.Extensions.Options with DedicatedSingleTenant: true, TenantSource: StaticConfiguration, and DefaultTenantId (see configuration schema). The resolver pipeline treats configuration-first before JWT tid—reducing dependency on external STS for that deployment mode.

Composite resolution

Default order (see ADR-0100):

  1. Static configuration (DedicatedSingleTenant / configured default tenant)
  2. JWT claim tid when RequireTenantClaim is required
  3. HTTP header X-Tenant-Id, optional host/subdomain strategy
  4. Transport-specific (gRPC metadata tenant-id, SignalR claims, messaging headers, Orleans context)

Templates must not fork ad hoc pipelines—consume ConnectSoft.Extensions.Saas.*.

Middleware order (ASP.NET Core)

Apply authentication (UseAuthentication) before tenant middleware that reads ClaimsPrincipal. Tenant middleware runs early after auth so ITenantContext is available for controllers, NHibernate session opening, and gRPC endpoints. Detailed ordering lives in ConnectSoft.Extensions.Saas.AspNetCore README and ADR-0100.

Hybrid default (deployment modes)

  • Shared DB with tenant row scoping. NHibernate EnableFilter + tenant parameter applies TenantId = :tenantId; strict rejection on scoped endpoints without context.
  • DatabasePerTenant — ITenantConnectionResolver selects connection string/registry entry per ITenantContext.
  • ResidencySilo — tenants align to DataSiloId/Residency. Cross-silo writes forbidden; cross-silo reads use ServiceModel peers.

gRPC and SignalR

  • gRPC: use metadata key tenant-id (claims remain tid). Package: ConnectSoft.Extensions.Saas.AspNetCore.Grpc.
  • SignalR: prefer JWT/handshake tid; fall back to connection metadata only when authenticated.

Each SaaS repo's docs/multitenancy.md mirrors this page; repos may live under C:\\Git\\ConnectSoft\\SAAS\\ or sibling paths—canonical list: saas-bounded-contexts-and-templates.

Documentation map

Topic Document
End-to-end SaaS platform (repos, templates, ServiceModel) SaaS platform — solution plan
Bounded contexts and template repo names SaaS bounded contexts and ConnectSoft.Saas.*Template
Per-repo acceptance checklist SaaS template baseline checklist
One-aggregate-root-per-repo map SaaS aggregate root assignment
Event envelopes + topic plan + idempotency SaaS cross-repo published language
Template dependency diagram (Platform + SaaS) Templates dependencies
Factory generation wiring SaaS factory generation wiring
Tenant propagation sequences multitenancy-sequences.md
Multitenancy JSON reference multitenancy-configuration-schema.md
Per-repo Integration handbooks (NuGet repos) SaaS extensions — package handbooks and integration
ADR — resolution / headers ADR-0100
Company-wide domain model ConnectSoft Company documentation — docs/saas/framework/saas-platform-ddd-entities.md

Out of scope

Dedicated configuration / feature-flag and audit platforms are not part of this multitenancy template program; treat them as separate bounded-context initiatives when adopted.