Tenant Isolation Patterns

Tenant Isolation Patterns

Activate when designing how multiple logical tenants coexist in one Salesforce environment: ISV managed package with customer orgs, multi-brand single org, franchise network, or multi-agency public sector deployment. Tenant isolation is an architect-level decision that touches sharing, packaging, customization, and integration.

Before Starting

• Distinguish logical tenants from separate orgs. If each tenant needs its own release cadence, compliance boundary, or governance model, use separate orgs and federate. If tenants share the same release train and just need data/config partitioning, multi-tenant within one org is viable.
• Know the regulatory posture. HIPAA, FedRAMP, GDPR data-residency requirements may make single-org multi-tenant legally infeasible.
• Audit the customization ask. Tenant-specific fields are hard in one org; tenant-specific record types and page layouts are easier; tenant-specific Apex is a smell.

Core Concepts

Tenant identifier on the record

Most common pattern: a Tenant__c lookup or picklist on every tenant-scoped object. Every query filters by tenant; every sharing rule gates by tenant. Simple, auditable, but dependent on discipline.

Account hierarchy as tenant

For B2B2C or franchise patterns, the tenant is an Account with a specific record type (e.g., "Franchisee"). Users roll up through the role hierarchy under that Account. Sharing falls out naturally from the role hierarchy.

ISV managed package isolation

In a managed-package ISV scenario, the customer's org IS the tenant boundary. Isolation is by org. Your concern is packaging, upgrades, and not leaking customer data through shared infrastructure.

Permission-based feature gating

Custom metadata or custom permissions define which features a tenant sees. Feature flags are queried at runtime; page layouts and UI conditionally render.

Common Patterns

Pattern: Single org, Tenant__c field, criteria-based sharing

Add Tenant__c to every tenant-scoped object. OWD is Private. Criteria-based sharing rules per tenant grant access to members of the tenant's permission set group. Reports filter by current user's Tenant ID.

Pattern: Franchise model via Account hierarchy

Each franchise is an Account with record type "Franchisee" plus a role for its users. OWDs private; role hierarchy handles franchise-to-franchise isolation. Regional managers span franchises via overlay role.

Pattern: ISV package with feature flags

Managed package ships with a Custom Metadata Type Feature_Flag__mdt. Each customer toggles flags without code changes. Apex checks flags via a central FeatureService.isEnabled('X') call.

Pattern: Multi-brand single org

Brand = Tenant. Each record stamped with brand. Users have a BrandId on User. Sharing rules gate by brand. Integrations receive brand-scoped tokens.

Decision Guidance

Recommended Workflow

1. Classify the tenant model: single-org logical, ISV managed package, or multi-org federated.
2. Write the isolation requirements: data, config, compliance, release cadence, integration.
3. Choose the tenant identifier strategy (field, account, namespace).
4. Design sharing: OWD, role hierarchy, criteria-based sharing, permission set groups.
5. Design feature gating: custom metadata, custom permissions, permission sets.
6. Build a tenant-onboarding runbook: records to create, permissions to grant, flags to set.
7. Test isolation with two-tenant data set; verify no cross-tenant visibility in reports, queries, dashboards.

Review Checklist

• Tenant model explicitly documented
• Tenant identifier chosen and consistently applied
• Sharing model validated with a two-tenant smoke test
• Feature flags in custom metadata or permissions, not Apex
• Onboarding runbook tested end-to-end
• Offboarding runbook (data export, access revocation) exists
• Cross-tenant reporting requirements addressed (aggregated view for owners)

Salesforce-Specific Gotchas

1. Role hierarchy bypasses sharing rules. A tenant admin role placed above another tenant's role grants visibility — model the hierarchy carefully.
2. Report folders do not have row-level filters. A tenant user seeing a shared report folder may see records from the report's query regardless of sharing — use CRM Analytics with security predicates for sensitive reporting.
3. Flow runs as the current user but can escalate. System Context flows bypass sharing and FLS; auditing flow run mode is a tenant-isolation imperative.

Output Artifacts

Related Skills

• architect/multi-org-architecture — sibling for federated model
• security/sharing-architecture — sharing detail
• devops/managed-package-publishing — ISV patterns
• standards/decision-trees/sharing-selection.md — when to use which sharing