By the time that ticket lands, the leak already happened. You can patch the query in an hour. What you cannot do is tell the affected garage how many other reports were wrong, how long it had been wrong, or whether anyone downloaded a CSV. There’s no log that answers those questions, because nothing ever denied anything. The database happily returned the rows. The API happily serialised them.

That’s the shape of the problem. Tenant isolation on AWS is not really about writing careful code. It’s about arranging things so that careless code fails loudly instead of quietly returning somebody else’s data.

This post walks through building a multi-tenant workshop management platform on AWS with isolation baked in from the first commit: where tenant context comes from, how the boundary changes shape per storage service, what the control plane has to own, and how you prove any of it works. The example is a shop management system, with job cards, vehicle histories, parts inventory and technician timesheets, but the patterns apply to any vertical SaaS product where one customer’s records must never touch another’s.

The failure mode that stays invisible

Most multi-tenant systems start with a tenant_id column and a convention: every query filters on it. That works right up until it doesn’t.

The convention breaks in ordinary ways. Someone adds a reporting endpoint and copies a query from a script that ran as an admin. A new join pulls in a table nobody remembered to filter. An ORM lazy-loads a relationship and the filter lives on the parent, not the child. A background job that recalculates parts margins runs without any tenant in scope at all, because it processes everything.

None of these throw. That’s the whole issue. A missing authorisation check produces a 403 you’ll notice in staging. A missing tenant filter produces a 200 with too many rows, and 200s don’t page anyone.

The fix is not more discipline. It’s moving the filter somewhere the application cannot forget it: into IAM, into the database engine, or both. AWS makes this point directly in its own SaaS guidance, and it’s the right one. If your only defence against cross-tenant reads is that developers remember, you don’t have a defence, you have a habit.

Pick the isolation model before you write code

There are three shapes, and they’re usually described as pool, silo and bridge.

• Pool. Every tenant shares the same tables, buckets and compute. Cheapest to run, cheapest to deploy, and the model where isolation has to be enforced explicitly because nothing physical separates anyone.
• Silo. Each tenant gets dedicated resources: its own database, its own bucket, sometimes its own account. Isolation is close to free, operations are not. Migrations, deploys and monitoring all multiply by tenant count.
• Bridge. Mixed. Shared compute, dedicated storage, or pooled for the standard tier and siloed for the enterprise tier that asked hard questions in procurement.

For a workshop platform, most independent garages will be small, and pooling is the only sane starting point. The trap is treating that as permanent. Sooner or later a dealer group with forty sites will ask for a dedicated database, and if you have not left room for a per-tenant routing decision, retrofitting it means rewriting your data access layer.

What I’d actually do: build pooled, but put the storage target behind a resolver from day one. A function that takes a tenant ID and returns a connection, a table name or a bucket prefix. When the first silo tenant arrives, you change the resolver, not four hundred call sites.

Where tenant context comes from

This is the part people get subtly wrong, and it undermines everything downstream. The tenant identifier must come from the authenticated identity, never from the request. Not a header, not a query parameter, not a field in the JSON body. If a client can influence the tenant ID, your isolation model is decoration.

In practice that means a custom claim in the token your identity provider issues. Amazon Cognito can carry a custom attribute for this, and so can any external IdP you federate with. The API layer reads the claim, and from that point the tenant is a fact about the caller rather than an input to the call.

Then you push that fact down into AWS itself using a session tag. When your service assumes a role, it attaches the tenant as a tag on the session. Every subsequent AWS API call made with those credentials carries the tag in the request context, where IAM policies can reference it as aws:PrincipalTag.

import boto3

def scoped_session(tenant_id, role_arn):
    sts = boto3.client("sts")
    resp = sts.assume_role(
        RoleArn=role_arn,
        RoleSessionName=f"workshop-{tenant_id}",
        Tags=[{"Key": "TenantID", "Value": tenant_id}],
    )
    c = resp["Credentials"]
    return boto3.Session(
        aws_access_key_id=c["AccessKeyId"],
        aws_secret_access_key=c["SecretAccessKey"],
        aws_session_token=c["SessionToken"],
    )

Two things make this work, and both are easy to miss. The role’s trust policy has to allow sts:TagSession alongside the assume-role action, or the call fails. And the calling principal needs permission to pass that tag. Get either wrong and you’ll spend an afternoon reading an error that sounds like it’s about the role rather than the tag.

One session tag, one role, one policy. That’s attribute-based access control, and it’s the reason ABAC scales where a role per tenant does not. Roles are a finite resource in an AWS account. Tags are not.

Tenant isolation on AWS changes shape per service

There is no single isolation control. Each service exposes a different lever, and you have to learn every one your architecture touches.

DynamoDB: the partition key is the boundary

If job cards live in DynamoDB with the tenant ID as the partition key, IAM can pin every read and write to that key. The condition key is dynamodb:LeadingKeys.

{
  "Effect": "Allow",
  "Action": [
    "dynamodb:GetItem",
    "dynamodb:PutItem",
    "dynamodb:UpdateItem",
    "dynamodb:Query"
  ],
  "Resource": "arn:aws:dynamodb:REGION:ACCOUNT:table/JobCards",
  "Condition": {
    "ForAllValues:StringEquals": {
      "dynamodb:LeadingKeys": ["${aws:PrincipalTag/TenantID}"]
    }
  }
}

Now a Query that omits the tenant partition key doesn’t return other tenants’ job cards. It gets denied. That’s the behaviour you want: loud, logged, and impossible to miss in CloudTrail.

Two caveats worth knowing before you commit. Scan operations don’t have a leading key to constrain, so granting dynamodb:Scan alongside this condition undermines the whole arrangement. And global secondary indexes have their own key structure, so an index whose partition key isn’t the tenant needs separate thought. Design the access patterns so that no query ever needs to look across tenants, and this stops being a problem.

S3: two surfaces, not one

Vehicle photos, inspection PDFs and signed job sheets go to S3 under a per-tenant prefix. The mistake is scoping only the object actions and leaving ListBucket open, which lets a tenant enumerate every other garage’s filenames even without reading them. Filenames leak plenty: customer names, registration plates, invoice numbers.

Object actions are scoped through the resource ARN. Listing is scoped through the s3:prefix request condition. You need both statements, because they protect different operations.

[
  {
    "Effect": "Allow",
    "Action": "s3:ListBucket",
    "Resource": "arn:aws:s3:::workshop-tenant-files",
    "Condition": {
      "StringLike": {
        "s3:prefix": ["${aws:PrincipalTag/TenantID}/*"]
      }
    }
  },
  {
    "Effect": "Allow",
    "Action": ["s3:GetObject", "s3:PutObject"],
    "Resource": "arn:aws:s3:::workshop-tenant-files/${aws:PrincipalTag/TenantID}/*"
  }
]

The policy variable in the resource ARN is doing real work there. One policy, every tenant, no template rendering at request time.

Aurora PostgreSQL: row-level security, and the trap in it

Relational data is where most workshop platforms actually live, because job cards, parts lines and labour rates are relational. IAM cannot see inside a table, so the boundary moves into PostgreSQL itself via row-level security.

ALTER TABLE job_cards ENABLE ROW LEVEL SECURITY;
ALTER TABLE job_cards FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON job_cards
  USING (tenant_id = current_setting('app.tenant_id', true))
  WITH CHECK (tenant_id = current_setting('app.tenant_id', true));

USING controls which rows are visible to reads, updates and deletes. WITH CHECK controls what can be written. Without the second clause, a tenant can read only its own rows but insert a row stamped with someone else’s tenant ID. The first protects the read path, the second protects the write path, and you want both.

Now the trap, and it’s the one that gives teams false confidence. PostgreSQL superusers and roles carrying BYPASSRLS ignore row security entirely, and by default so does the table owner. If your application connects as the same role that ran the migrations, your policies are not in effect and your tests pass anyway. That’s why FORCE ROW LEVEL SECURITY is in the snippet above, and why the application should connect as a dedicated non-owner, non-superuser role.

The second trap is connection reuse. Set the tenant with SET LOCAL inside a transaction, or with set_config using the transaction-local flag. Plain SET persists for the life of the connection, and a pooled connection outlives the request. That’s how one garage’s context ends up serving the next garage’s query.

Test row-level security as the application role, against a pooled connection, with at least two tenants in the table. Testing as the owner tells you nothing.

Compute isolation is a different question

Data isolation stops one tenant reading another’s records. It does nothing about one tenant consuming everyone’s capacity.

Workshop platforms have a specific version of this. End of month, every garage runs its invoicing and MOT reminder batch at roughly the same time. A dealer group importing three years of service history will happily saturate a shared worker pool while forty independents wait for their job cards to load.

Levers worth knowing, roughly in order of how much they cost you:

• API Gateway usage plans, keyed per tenant, to cap request rates at the edge before anything expensive runs.
• Separate queues, or at minimum separate consumer concurrency, for bulk imports versus interactive requests. Bulk work should never share a lane with a screen someone is waiting on.
• Reserved or provisioned concurrency on the Lambda functions serving interactive paths, so a batch surge cannot starve them.
• Dedicated compute for premium tenants. This is silo by another name, and it’s the honest answer when a customer’s load profile genuinely doesn’t fit the pool.

Be honest with yourself about which problem you’re solving. Throttling is not isolation. It limits blast radius, it doesn’t create a boundary.

What the control plane has to own

Separate the control plane from the application plane early. The control plane manages tenants; the application plane serves them. Mixing the two is how a bug in the onboarding flow ends up with production credentials.

Onboarding a new workshop is a sequence, and it should be a single idempotent workflow rather than a checklist someone follows:

1. Generate a non-guessable tenant identifier. Lowercase alphanumeric, no customer name in it, because it will end up inside resource ARNs and key prefixes.
2. Write the tenant record: tier, isolation model, storage target, status.
3. Provision identity. User pool group or IdP mapping, with the tenant claim wired in.
4. Provision storage. For a pooled tenant that’s a prefix and a seeded row. For a siloed one it’s real infrastructure, which is why this step must be asynchronous.
5. Apply tags used for cost allocation and reporting.
6. Run a verification step that proves the new tenant can reach its own data and cannot reach a canary tenant’s data.

Step six is the one teams skip. It’s also the only step that tells you the previous five worked.

On per-tenant cost: activated cost allocation tags attribute anything that is a distinct tagged resource, which covers siloed tenants nicely. Pooled resources will not split by themselves, because a shared table doesn’t know which garage caused which read. If you need per-tenant margin, emit consumption as a metric dimension from the application: request counts, storage bytes, document pages processed. Tools like Vantage or CloudZero can allocate shared spend afterwards, but only from the signal you produce. Nothing recovers attribution you never recorded.

The AWS SaaS Builder Toolkit is worth a look here. It codifies control plane concepts as CDK constructs and will save you real time on onboarding plumbing. Read its own guidance first: the project describes itself as sample code, and expects you to review security fit before production. That’s a fair description rather than a warning label, but treat it as a starting point, not a finished platform.

Proving isolation actually holds

An isolation model you haven’t tried to break is a design document, not a control.

The tests that earn their keep are negative ones. Seed two tenants. Authenticate as the first. Then deliberately do the wrong thing: request the second tenant’s job card by ID, list the second tenant’s S3 prefix, run a query with the session variable set to the wrong value. Every one of those should fail, and the test should assert on the failure.

• Run the cross-tenant suite on every pull request, not nightly. It’s the regression that matters most and the one most likely to be introduced by an innocent refactor.
• Use the IAM policy simulator to check a policy change before it ships, particularly when someone widens a resource ARN.
• Turn on IAM Access Analyzer so external access grants surface without anyone having to notice them.
• Audit the database on a schedule: tables with RLS enabled but no policy attached, tables missing FORCE, application roles that have quietly acquired ownership or BYPASSRLS during an incident.
• Alert on AccessDenied volume per tenant. A spike is either a bug you introduced or someone probing, and both are worth knowing about.

Keep a permanent canary tenant in every environment, including production, holding nothing but synthetic data. Every negative test targets it. It costs almost nothing and it means your isolation tests never need real customer records.

Troubleshooting the failures you’ll actually hit

AccessDenied on a policy that looks correct

Almost always the session tag isn’t present. If the tag is missing from the request context, the condition can’t match and the statement doesn’t apply. Call sts:GetCallerIdentity with the scoped credentials and confirm you’re on the assumed role you think you are, then check CloudTrail for the AssumeRole event and look at whether the tag was actually passed. Tag keys are case sensitive, and TenantId is not TenantID.

Queries return zero rows instead of the right rows

Classic RLS symptom. The session variable is unset, so the policy predicate compares against null and nothing matches. Check current_setting inside the same transaction as the query, not in a separate connection from your SQL client. Empty results are the safe failure here, which is exactly why they’re easy to misread as a data problem.

One tenant intermittently sees another’s data

Intermittent means state reuse. Look at connection pooling first, then at any per-request context stored in thread-local or async-local storage that isn’t reset when the request finishes. If you’re using a proxy in front of the database, understand how it handles session state, because some proxies pin a connection to a client once session-level settings are detected, which changes the behaviour you tested against.

Isolation works in the API but not in background jobs

Because the job has no request, so it has no token, so it has no tenant. Whatever runs asynchronously needs the tenant carried on the message and a session assumed per tenant when the work is processed. A worker that loops over all tenants with admin credentials is the single most common place isolation quietly stops applying.

Session tags don’t survive a second AssumeRole

Session tags are not automatically carried forward when you chain roles unless they were marked transitive. If your architecture hops through more than one role, this is where the tenant context evaporates. Flatten the chain if you can; if you can’t, mark the tag transitive deliberately and document why.

Common mistakes

• Taking the tenant ID from a request header or body instead of the authenticated token.
• Using the customer’s name or a sequential integer as the tenant identifier, then putting it in bucket prefixes where it becomes both guessable and enumerable.
• Scoping S3 object actions but leaving bucket listing wide open.
• Running the application as the PostgreSQL table owner, so RLS is enabled and silently inert.
• Writing a USING clause with no WITH CHECK, leaving the write path open.
• Creating one IAM role per tenant and discovering the account ceiling somewhere around the point the business gets interesting.
• Assuming cost allocation tags will attribute pooled spend. They won’t, and by the time you need the numbers the history is gone.
• Testing isolation only through the UI, where the frontend is already sending the right tenant every time.

Best practices worth the effort

• Derive tenant context from the token, propagate it as a session tag, and never let application code choose it.
• Enforce the boundary at the layer below your code: IAM conditions for AWS resources, RLS for relational rows.
• Put storage targets behind a resolver so moving a tenant from pool to silo is a configuration change.
• Make onboarding one idempotent workflow that ends in a verification step.
• Emit tenant as a dimension on logs and metrics from the start, so cost and performance questions stay answerable.
• Keep a canary tenant and run cross-tenant negative tests in CI on every change.
• Put a WAF or edge layer such as Cloudflare in front of tenant subdomains, and keep tenant routing decisions out of the origin application where you can.

Frequently asked questions

Is a shared database with a tenant_id column ever acceptable?

Yes, provided the column is enforced by the engine rather than by convention. A shared table with row-level security, forced, queried by a non-owner role, is a real boundary. A shared table where every query is expected to include the filter is not. The schema is the same; the guarantee is completely different.

ABAC or dynamically generated IAM policies?

ABAC for most cases. One role, one policy, tenant supplied per session, and nothing grows as you add customers. Dynamic policy generation, sometimes called a token vending machine, earns its place when a single policy genuinely cannot express the rule, such as when per-tenant resource names have to be injected rather than a key prefix. The cost is that you now own the correctness of a policy generator, plus per-request latency, and session policies have a size ceiling you can hit.

Should each tenant get its own AWS account?

It’s the strongest boundary available and the most expensive to operate. For a workshop platform serving independent garages it’s overkill. It becomes reasonable when a customer’s contract, regulator or data residency requirement makes shared infrastructure a non-starter, and at that point you’re pricing it as a premium tier rather than absorbing it.

How do I handle a user who works at two workshops?

Model it as one identity with multiple tenant memberships and an explicit active tenant per session, rather than a token carrying a list. The active tenant becomes the session tag. Switching workshops means a new session, which is exactly the behaviour you want because it makes the switch visible in your audit trail.

Does row-level security hurt query performance?

It adds a predicate the planner has to satisfy, so the answer depends on your indexes. Index the tenant column, and index it as the leading column of composite indexes that support your common filters. Compare plans as the application role before and after enabling policies, because a plan captured as the owner may not reflect what the application actually runs.

Where does application-level authorisation fit?

Alongside, not instead. Tenant isolation answers “which organisation’s data is this”. Authorisation answers “may this technician void an invoice”. Different questions, different layers. A policy engine such as Amazon Verified Permissions handles the second cleanly, and keeping them separate stops role logic creeping into your isolation boundary.

Can I retrofit isolation onto a platform that already has tenants?

You can, and it’s tedious rather than impossible. Enforce at the database first, because that’s where the leak actually happens: table by table, FORCE enabled, application moved to a non-owner role. Then move the tenant ID out of request payloads and into the token. Add IAM conditions last, since they’re the least likely source of a live leak. Expect to find at least one background job with no tenant scope at all.

The one thing to remember

Tenant isolation on AWS works when the boundary sits below your application code, in a layer that denies rather than trusts. IAM conditions on session tags for AWS resources, forced row-level security for relational data, and a control plane that verifies a new tenant is properly fenced before anyone logs in.

Retrofitting that onto a running multi-tenant platform is possible but grim, because you’re doing it while real workshops have real data in the system. Doing it on day one costs a week. That’s the entire trade, and it’s not a close call.

Need a second pair of eyes on your multi-tenant architecture?

Most of the isolation problems I see are not exotic. They’re a missing WITH CHECK clause, an application connecting as the table owner, or a background job nobody scoped. Things I can help with:

• Reviewing an existing multi-tenant design and finding where the boundary is enforced by convention rather than by the platform.
• Implementing ABAC with STS session tags across DynamoDB, S3 and Aurora, including the trust policy wiring that trips people up.
• Setting up PostgreSQL row-level security correctly, with forced policies, a dedicated application role and pooling that doesn’t leak session state.
• Building a tenant onboarding workflow that provisions identity, storage and tagging idempotently and verifies itself.
• Writing the cross-tenant negative test suite and wiring it into CI so isolation regressions fail the build.
• Adding per-tenant usage metering so cost, performance and tier decisions rest on data instead of guesses.

Send me a policy document, an RLS definition or a CloudTrail AccessDenied event and I’ll tell you what it’s actually enforcing.

The post Tenant Isolation on AWS: Building a Multi-Tenant Workshop Platform That Doesn’t Leak appeared first on John Nessime.