CONCEPT Cited by 7 sources
Tenant isolation¶
What it is¶
Tenant isolation in a multi-tenant SaaS is the property that one tenant's users, data, and policies are strictly inaccessible to other tenants — enforced at every layer where cross-tenant leakage is possible (identity, authorization, compute, storage, network).
This is a layered property: a correctly isolated system enforces tenant boundaries redundantly, so a bug in any single layer cannot leak across tenants.
Isolation layers (Convera's shape)¶
- Identity layer. Tenant-specific Cognito
pool with a custom
tenant_idattribute on each user. Users physically cannot be a member of another tenant's pool. - Token layer. Pre-token
hook injects
tenant_idinto the JWT claim at issue time, fetched from a DynamoDB user → tenant mapping. The tenant binding is now cryptographically signed inside the token. - Authorization layer. A
[[patterns/per-tenant-policy-store|per-tenant
AVP policy store]].
Policies are physically separate; a policy in tenant A's store
cannot refer to resources in tenant B's. Authorizer looks up
tenant_id → policy-store-idin DynamoDB and calls AVP against the tenant-specific store. - Request-routing layer. API Gateway forwards to backend
Kubernetes pods with
tenant_idin a custom request header. - Data layer. Backends re-validate with AVP (patterns/zero-trust-re-verification) against the tenant's policy store before hitting RDS; RDS is "configured to accept only requests with specific tenant context and returns data specific to the requested tenant_id."
Even if upstream layers are compromised or buggy, the RDS-side tenant-context enforcement is the last line of defense.
(Source: sources/2026-02-05-aws-convera-verified-permissions-fine-grained-authorization)
Key decisions¶
- Per-tenant policy store vs single store with tenant-scoped policies. Convera chose per-tenant for isolation, customization, onboarding/offboarding, and per-tenant resource quotas. See patterns/per-tenant-policy-store for the tradeoff analysis.
- Where tenant context is sourced. Every layer must source
tenant_idfrom a place the tenant cannot spoof — JWT claim from authoritative Cognito pool, not request body, not URL path. - Zero-trust vs trust-boundary model. Convera's architecture is explicitly zero-trust: every tier re-verifies. Alternative: the API-Gateway boundary is the only verification point, everything behind it is trusted. The zero-trust pattern costs extra AVP calls per request but protects against compromised-backend and misconfigured-policy scenarios.
Related isolation-shape comparisons¶
- Airbnb Himeji — data-layer authorization with per-context Profile IDs and write-time relation denormalization. Different substrate (not AVP), same "enforce at the lowest layer possible" instinct.
- Airbnb metrics storage — shows tenant isolation at the infrastructure layer rather than the authorization layer: per-tenant shuffle sharding assigns each tenant a K-node subset of ingesters and query workers, so a noisy tenant saturates their shuffle set but not others. Tenant-per-application mapping (patterns/tenant-per-application) rather than tenant-per-team because service ownership is more stable than team ownership. Complements the Convera / ProGlove shapes which are about authorization; Airbnb's is about performance / availability isolation for a shared stateful system.
- concepts/least-privileged-access — the individual-scope twin; tenant isolation is the tenant-scope enforcement of the same principle.
Caveats¶
- Isolation cost scales with tenant count. Per-tenant policy store works up to AVP's per-account store limit (not disclosed in Convera source); beyond that, a shared-store-with-tenant-scoped- policies variant is required.
- Cross-tenant admin operations (a platform-admin role that legitimately sees across tenants) must be carefully modeled — they intentionally violate tenant isolation and need their own set of policies + audit.
- Tenant onboarding latency. Creating a new policy store, provisioning a new Cognito pool, and seeding user mappings is not instantaneous; SaaS onboarding UX has to account for this.
Shape 6 — Cluster-level isolation in shared accounts (AWS hybrid multi-tenant)¶
AWS ad-serving platform (Source: sources/2026-05-12-aws-building-hybrid-multi-tenant-architecture-for-stateful-services) canonicalises a new shape on the wiki's isolation-spectrum: cluster-per-tenant inside a shared AWS account, with everything else (VPC, ALB, IAM, PrivateLink) shared at tier level. This sits structurally between the in-account authorization-engine shape (Convera) and the account-per-tenant shape (ProGlove):
- The compute cluster is the tenant boundary — a dedicated ECS cluster per tenant, loading only that tenant's in-memory state. No shared heap.
- Account is shared — no account-per-tenant onboarding tax; dependencies pre-wired at tier creation.
- The driver is in-memory tenant state — stateful services where one tenant's heap growth can OOM neighbors.
See concepts/cluster-level-tenant-isolation for the full shape analysis and patterns/hybrid-multi-tenant-architecture for the canonical pattern.
Updated isolation-shape spectrum now has six distinct shapes:
| # | Shape | Boundary | Canonical source |
|---|---|---|---|
| 1 | Shared account + JWT-only + app-layer enforcement | App layer | sources/2026-04-08-aws-build-a-multi-tenant-configuration-system-with-tagged-storage-patterns |
| 2 | Shared account + per-tenant AVP + data-layer re-verification | Multi-layer in account | sources/2026-02-05-aws-convera-verified-permissions-fine-grained-authorization |
| 3 | Account-per-tenant | AWS account | sources/2026-02-25-aws-6000-accounts-three-people-one-platform |
| 4 | IAM-role-per-tenant via Cognito | IAM credentials | sources/2026-04-22-aws-pacific-multi-tenant-sovereign-pcf-exchange-catena-x |
| 5 | Shuffle-sharded compute pool | Shuffle set | sources/2026-04-21-airbnb-building-a-fault-tolerant-metrics-storage-system |
| 6 | Cluster-per-tenant in shared account | ECS cluster | sources/2026-05-12-aws-building-hybrid-multi-tenant-architecture-for-stateful-services |
Seen in¶
- sources/2026-05-14-instacart-scaling-personalized-marketing-for-multi-tenant-commerce-platforms — seventh shape on the isolation-spectrum (see above). Instacart Storefront Pro's marketing-automation layer provisions a dedicated workspace per retailer inside a third-party SaaS provider; the vendor, not the platform, enforces the boundary at the workspace grain (data, templates, configuration, rate-limit budget, failure-isolation domain). First wiki shape where the boundary lives outside the platform's own infrastructure. 350+ retailer workspaces, 99.9% delivery success, zero cross-retailer data-leakage incidents. Pairs with patterns/vendor-abstraction-service-layer to preserve the swap-vendor option against the workspace non-portability tradeoff.
- sources/2026-05-12-aws-building-hybrid-multi-tenant-architecture-for-stateful-services — sixth shape on the isolation-spectrum (see above). AWS's stateful ad-serving platform's migration from account-per-tenant cellular architecture to cluster-per-tenant in shared accounts. The canonical instance of the hybrid shape where isolation grain is chosen per-layer: compute (cluster-level isolated), network (shared VPC + ALB + PrivateLink at tier), identity (shared IAM role at tier). 52d → 7d onboarding improvement attributed primarily to pre-integrating shared dependencies at tier creation.
- sources/2026-02-05-aws-convera-verified-permissions-fine-grained-authorization
— full five-layer isolation chain for Convera's multi-tenant SaaS
mode; per-tenant Cognito pool +
tenant_idJWT claim + per-tenant AVP policy store + tenant-header propagation to backend + data-layer re-verification. - sources/2026-04-14-airbnb-privacy-first-connections — Airbnb's fellow-traveler privacy model; tenant-analog enforcement at the data layer.
- sources/2026-02-25-aws-6000-accounts-three-people-one-platform — the opposite end of the spectrum: ProGlove enforces tenant isolation at the AWS account boundary rather than inside a shared account at multiple authorization layers. See concepts/account-per-tenant-isolation for the shape- comparison.
Isolation-shape spectrum (added 2026-04-21)¶
Tenant isolation admits at least three architectural shapes, on a spectrum of where the enforcement boundary lives:
| Shape | Boundary | Canonical source |
|---|---|---|
| Shared account + JWT-only tenant claim + app-layer tenant-scoped queries (lightest) | Identity + app-layer | sources/2026-04-08-aws-build-a-multi-tenant-configuration-system-with-tagged-storage-patterns — tagged-storage config service, patterns/jwt-tenant-claim-extraction + DynamoDB composite-key isolation |
| Shared account + per-tenant AVP policy store + backend zero-trust re-verification + data-layer tenant-context enforcement | Multi-layer inside the account | sources/2026-02-05-aws-convera-verified-permissions-fine-grained-authorization |
| Account-per-tenant — dedicated AWS account per tenant | AWS account | sources/2026-02-25-aws-6000-accounts-three-people-one-platform — see concepts/account-per-tenant-isolation |
The multi-tenant-config post is the lightest of the three — single shared account, no per-tenant AWS resources, application-layer enforcement with JWT-sourced tenant context + DynamoDB composite-key partitioning as the structural safety net. Convera's is in-account multi-layer. ProGlove's is structural per-account. All three deliver tenant isolation; they trade operational complexity against isolation strength.
Convera's shape is isolation through application-layer redundancy. ProGlove's shape is isolation through structural separation. Both deliver the property; they make different trade-offs about where the operational complexity lives (authorization engine vs. platform automation).
Related¶
- patterns/per-tenant-policy-store — the AVP mechanism.
- patterns/zero-trust-re-verification — the layered-enforcement pattern.
- patterns/cognito-group-to-iam-role-mapping — the PACIFIC variant: IAM-role isolation via Cognito → STS.
- concepts/fine-grained-authorization, concepts/least-privileged-access.
- concepts/policy-as-data — policies per tenant still need authoritative write-side governance.
Shape 5 — IAM-role-per-tenant via Cognito (PACIFIC)¶
PACIFIC (Source: sources/2026-04-22-aws-pacific-multi-tenant-sovereign-pcf-exchange-catena-x) delivers isolation by making the AWS credentials themselves tenant- scoped. Each tenant gets a Cognito user-pool group linked to a dedicated IAM role with a policy that grants Secrets-Manager access only to that tenant's secret. The Cognito identity pool maps group membership to role; AWS STS issues temporary credentials scoped to that role. A user's credentials are structurally incapable of reading cross-tenant resources — the denial happens at IAM, not in the app. No account-per-tenant, no VPC-per-tenant; onboarding is synchronous role-creation rather than account-provisioning. See patterns/cognito-group-to-iam-role-mapping for the mechanism.
Contrast axes across the five shapes now on the wiki:
- Convera: in-account, layered application + authz-engine enforcement (layered-redundancy-through-AVP).
- ProGlove: per-account, structural separation (account-per-tenant).
- Datadog CDC platform: tagged-storage + JWT-claim enforcement.
- Airbnb metrics storage: shuffle-sharded compute pool.
- PACIFIC: in-account, IAM-role scoped credentials (credentials-structurally-incapable-of-cross-tenant-access).
Shape 7 — Per-tenant workspace in third-party SaaS (Instacart Storefront Pro)¶
Instacart Storefront Pro's marketing-automation layer (Source: sources/2026-05-14-instacart-scaling-personalized-marketing-for-multi-tenant-commerce-platforms) canonicalises a new shape on the spectrum: the tenant boundary is an opaque "workspace" inside a third-party SaaS that the platform provisions and operates programmatically. The vendor itself enforces the boundary — data, configuration, templates, identity, and (in the marketing-automation case) per-tenant rate-limit budget are separated at the workspace grain. The vendor, not the platform, owns the isolation primitives.
Verbatim: "We provision a dedicated workspace for each retailer within the third-party provider. A workspace is an isolated account with its own customer data, templates, and configuration. This per-retailer workspace model guarantees data isolation and brand integrity across the platform."
This is the only shape where the third party operates the boundary. The platform's job becomes:
- Provisioning workspaces programmatically as new tenants onboard.
- Routing every per-tenant request to the correct workspace.
- Building the operational machinery the vendor doesn't provide (bulk template deployment, automated IP warming, metric aggregation across workspaces, vendor abstraction).
Disclosed properties at Storefront Pro: 350+ retailer workspaces, 99.9% delivery success across all retailers, zero cross-retailer data-leakage incidents.
See concepts/per-tenant-workspace-isolation for the full shape analysis and patterns/per-tenant-workspace-in-third-party-saas for the canonical pattern.
Updated isolation-shape spectrum now has seven distinct shapes:
Shape 7 sits structurally outside the rest of the spectrum — it is the only shape where the platform team doesn't operate the boundary itself. That makes it cheap to bootstrap (the vendor already implements isolation primitives) but introduces vendor lock-in (workspaces are non-portable), motivating the pairing with vendor abstraction to preserve the swap-vendor option.