PrimusSaaS.MultiTenancy 1.2.0

PrimusSaaS.MultiTenancy

Release status: stable.

Core package for tenant context, resolution contracts, and multi-tenancy options.

The core runtime and package integrations are validated in the current workspace. Remaining work is ecosystem expansion and broader repo hygiene, not a current code-path release blocker.

Validation

• Current workspace validation: 479/479 tests passed on net8.0, net9.0, and net10.0
• Current workspace validation: coverage stayed above the configured threshold on all three frameworks (97.05% line / 87.77% branch on net8.0)
• Scope boundary: core resolution/isolation/runtime only; tenant provisioning and platform workflows stay outside the core package

Telemetry

• Emits ActivitySource spans for tenant resolution, isolation, propagation, diagnostics, and feature-flag bridge flows.
• Consumers still need to wire their own exporter if they want those spans collected outside the process.
• The package intentionally stays exporter-agnostic and does not force a telemetry backend.

For a verified new-app onboarding path that combines Identity Validator + Multi-Tenancy + RBAC in one ASP.NET Core host, use the Docusaurus guide at /docs/modules/combined-dotnet-integration.

Quick start

builder.Services.AddPrimusMultiTenancy(options =>
{
 options.TenantClaimType = "tid";
 options.TenantHeaderName = "X-Tenant-Id";
 options.TenantRouteKey = "tenantId";
 options.EnableSubdomainResolution = false;
 options.RequireTenantOnAuthenticatedRequests = true;
 options.EnableTenantRateLimiting = true;
 options.RateLimitMaxRequests = 100;
 options.RateLimitWindow = TimeSpan.FromMinutes(1);
});

Options reference

Default resolver precedence

1. Claims (TenantClaimType)
2. Header (TenantHeaderName)
3. Route value (TenantRouteKey)
4. Subdomain — opt-in via EnableSubdomainResolution
5. Active membership via ITenantMembershipStore

Related packages

• PrimusSaaS.MultiTenancy.AspNetCore — middleware pipeline extensions (UsePrimusTenantResolution, UsePrimusTenantIsolation, UsePrimusTenantRateLimiting)
• PrimusSaaS.MultiTenancy.EFCore — write interceptor and ModelBuilder schema enforcement
• PrimusSaaS.MultiTenancy.InMemory — in-memory ITenantMembershipStore for development and tests
• PrimusSaaS.MultiTenancy.Dapper — Dapper + PostgreSQL / SQL Server tenant and membership stores
• PrimusSaaS.MultiTenancy.MongoDB — MongoDB tenant and membership stores
• PrimusSaaS.MultiTenancy.CosmosDB — Azure Cosmos DB tenant and membership stores
• PrimusSaaS.MultiTenancy.Redis — Redis-backed ITenantStore and ITenantRateLimiter
• PrimusSaaS.MultiTenancy.FeatureFlags — tenant-scoped feature flag bridge to PrimusSaaS.FeatureFlags

Security

These configuration defaults are safe for local development but must be reviewed before deploying to staging or production:

1. TrustedHeaderSourceIPs — header tenant injection risk

TrustedHeaderSourceIPs defaults to an empty set. When empty, the HeaderTenantResolutionStrategy accepts X-Tenant-Id from any client IP, allowing a malicious caller to inject an arbitrary tenant.

Required in staging/production: either configure a trusted IP list, or register AddPrimusMultiTenancyMembershipValidatedSelection() so header values are validated against the caller's actual memberships before acceptance. The production/staging startup validator (MultiTenancyProductionValidationHostedService) will throw at startup if HeaderTenantResolutionStrategy is active without MembershipValidatedTenantResolutionStrategy.

options.TrustedHeaderSourceIPs = new HashSet<string> { "10.0.0.1", "10.0.0.2" }; // internal proxies only

2. AllowedPropagationHosts — tenant ID leakage to third-party APIs

AllowedPropagationHosts defaults to an empty set. When empty, the TenantPropagationDelegatingHandler forwards the X-Tenant-Id header to every outbound HttpClient call, including calls to third-party payment providers, analytics services, and external APIs.

Required in staging/production: configure the set of internal hosts to limit propagation:

options.AllowedPropagationHosts = new HashSet<string>
{
 "api.internal.example.com",
 "payments.internal.example.com"
};

3. MapPrimusTenantManagementEndpoints — admin endpoints unsecured by default

MapPrimusTenantManagementEndpoints() with no authorizationPolicy parameter maps full tenant CRUD (create, update, suspend, hard-delete, offboard) with no authentication.

Always pass a policy in staging/production:

app.MapPrimusTenantManagementEndpoints(
 pattern: "/admin/tenants",
 authorizationPolicy: "PrimusPlatformAdmin");

A warning is logged at startup when endpoints are mapped without a policy.

New extension points

• TenantContextSnapshot — preferred unified snapshot API for capturing, transporting, and restoring tenant state across request and background execution scopes.
• ITenantRateLimiter — plug in a distributed limiter implementation (for example Redis-backed) to enforce tenant limits across instances.
• ITenantStore helper extensions: SuspendTenantAsync(...), ActivateTenantAsync(...), SoftDeleteTenantAsync(...)
• ITenantMembershipStore helper extension: GetAccessibleTenantsAsync(...) for tenant switcher scenarios
• AddPrimusMultiTenancyMembershipCaching(...) — wraps the registered membership store with IMemoryCache.
• ITenantDataRetentionService — contract for deleting all tenant-owned data during offboarding.
• ITenantFeatureFlagBridge — default bridge to PrimusSaaS.FeatureFlags that fail-closes when no flag service is registered.