Enforce tenant access in APIs, caches and exports

Application background

Acme and Birch use the same report application, but each company expects its data to remain private. A company account is called a tenant. Its members may request reports, reuse previously generated results and download exported files.

Checking the company only on the first page is not enough. A guessed report ID, a saved download link or a queued export can reach the same data through another route. A person can also lose permission after work has already started.

Example walkthrough

Every path to the data must use the current tenant and permission rules. A cache is a reusable copy of a result, not a separate source of permission.

Your assignment

Deliver: Build report reads and exports that enforce the requesting company's current permissions. Demonstrate what happens to cached results and waiting exports when access is removed.

Required behavior: Every request has one verified tenant context. GET /reports/{id}, export creation and export download must authorize the resource under that context. Do not trust an X-Tenant-ID header independently of membership.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/tenant_isolation.py

Supplied file: examples/architecture-starts/tenant_isolation.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for tenant-isolation. No AWS resources are created."""
reports={('acme','r1'):'Acme revenue',('birch','r2'):'Birch payroll'}
members={('ana','acme')}; cache={('acme','r1'):'Acme revenue'}
def read(user,tenant,rid):
    if (user,tenant) not in members: return '403 membership revoked'
    return cache.get((tenant,rid),reports.get((tenant,rid),'404 scoped resource'))
print(read('ana','acme','r2'))
print(read('ana','acme','r1'))
members.remove(('ana','acme'))
print(read('ana','acme','r1'))

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

404 scoped resource
Acme revenue
403 membership revoked

Set up your implementation workspace

Create work/tenant-isolation/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Create trusted request context

Resolve the authenticated subject’s active organization and role. Reject a requested tenant without membership. Make repository methods require a tenant argument. Avoid an unscoped get-by-ID convenience method that callers can accidentally use.

2. Protect cached and asynchronous reads

Key caches with tenant and object version. Check current authorization before returning cached content. A worker loads the job’s verified tenant and requester, then checks current access before generating bytes. Never accept a queue-provided object prefix as unrestricted filesystem or bucket authority.

3. Make export access revocable

Keep exports private. Reauthorize each new download request. A presigned URL remains usable until expiry, so choose a short documented window or proxy every download if immediate revocation is required. Revocation must also stop future regeneration from queued jobs.

4. Bound tenant resource use

Add per-tenant admitted-job counters and a fair scheduler. Show Acme over its limit while Birch continues making progress. Partition metrics by bounded tier or top offenders instead of creating millions of uncontrolled labels.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

A shared database can be safe when tenant scope is enforced consistently. Dedicated databases trade cost and operating complexity for a stronger isolation boundary. Choose that for requirements that application-level scoping cannot satisfy.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Move one tenant into dedicated storage

An enterprise customer wants independent recovery and access controls. Forking every endpoint would make the two products drift. The new responsibility is deciding where a tenant lives and preventing stale workers from writing to its old home.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Add a trusted placement record keyed by tenant with location, state and generation. Resolve it after authentication in both HTTP and worker paths. Copy one snapshot, apply newer changes and tombstones, then briefly quiesce that tenant's writers to reconcile and switch placement. Fence old-generation writes at the storage boundary. Move credentials and encryption access with the placement. In AWS, the dedicated target can be a separate RDS database or account-scoped table, with an assumed role restricted to that tenant.

Walk through the result. Move tenant T while tenant U continues normally. Resume an old T export after cutover. It must refresh its placement or fail, not read from the pooled copy. Reconcile values and deletions before routing. Keep the old copy inaccessible until its retention and rollback obligations end.

Offer dedicated storage to a regulated customer without forking the entire application. Define tenant placement metadata, connection routing, restore scope and the migration boundary between shared and dedicated storage.