Skip to content

Multitenancy configuration (reference)

Copy into each SaaS template docs/configuration.md and appsettings samples. Section name: Multitenancy.

{
  "Multitenancy": {
    "DeploymentKind": "SharedDb",
    "DedicatedSingleTenant": false,
    "RequireTenantClaim": true,
    "DefaultTenantId": null,
    "TenantSource": "ResolverPipeline",
    "TenantResolutionStrategy": "ConfigurationFirstThenJwtThenHeaders",
    "HttpTenantHeaderName": "X-Tenant-Id",
    "JwtTenantClaimType": "tid",
    "MessagingTenantHeaderName": "tenant-id",
    "EnableHttpHostSubdomainTenant": false,
    "HostDerivedTenantTrustedHostSuffix": null,
    "TenantCatalog": [],
    "TenantConnectionStrings": null,
    "TenantOptionsSink": {
      "SlidingExpiration": "00:15:00"
    }
  }
}
Value Meaning
TenantSource = StaticConfiguration Installation-only: effective tenant from DefaultTenantId / options; use with DedicatedSingleTenant: true.
TenantSource = ResolverPipeline Full composable resolver (configuration branch first when DedicatedSingleTenant).
DeploymentKind SharedDb | DatabasePerTenant | ResidencySilo — drives persistence partitioning; TenantConnectionStrings feeds ITenantConnectionResolver when populated.
TenantResolutionStrategy Diagnostics / ordering hint (TenantResolutionStrategyKind); Saas.AspNetCore applies ITenantHttpResolutionContributor instances by Order (host subdomain 10, configured HTTP header 100) — correlate with HostSubdomainContributorBeforeConfiguredHeader when documenting host policy.
JwtTenantClaimType JWT claim inspected after authentication (fallback SaasClaimTypes.TenantId inside TenantResolutionInput when claim absent).
MessagingTenantHeaderName MassTransit ConsumeContext.Headers and NServiceBus MessageHeaders inbound key — defaults tenant-id (gRPC unary metadata uses the same canonical key via **SaasTransportConstants.GrpcAndMessagingTenantKey).
EnableHttpHostSubdomainTenant When true, derive tenant hint from Host (Saas.AspNetCore) — HostDerivedTenantTrustedHostSuffix required.
HostDerivedTenantTrustedHostSuffix Trusted apex DNS suffix (e.g. contoso-apps.com).
TenantCatalog Static TenantCatalogItem rows for ConfigurationTenantStore (ITenantStore).
TenantConnectionStrings Tenant id → ADO.NET connection string map for MultitenancyTenantConnectionResolver.
TenantOptionsSink Sliding expiration for DefaultTenantOptionsSink (process-local IMemoryCache only).

See ADR-0100 for resolution order and trust boundaries.