Multi-Tenancy & Delegation¶
What it is¶
Multi-tenancy means one API serves many customers (tenants) whose data must never cross. Delegation means one identity acts on behalf of another — a support agent impersonating a user, a service calling another service for a user, or a third-party app acting with the user's consent. Both are authorization problems where a single missed check exposes someone else's data.
How it works¶
Tenant isolation layers¶
Editable source: docs/diagrams/tenant-isolation.drawio
| Isolation level | How | Trade-off |
|---|---|---|
Shared tables + tenant_id column |
Every query filters by tenant | Cheapest; one missed WHERE is a cross-tenant breach |
| Shared tables + row-level security | Database enforces the filter | Defense in depth; requires session-level tenant context |
| Schema / database per tenant | Connection routed by tenant | Stronger isolation; more operational overhead |
| Per-tenant encryption keys | Data encrypted with tenant-specific KMS keys | Crypto-shredding on offboarding; key-management cost |
Tenant comes from the token, never from the request
X-Tenant-ID: acme in a header or ?tenant=acme in a query string is
attacker-controlled. Derive the tenant from the verified token (or from
a server-side lookup of the authenticated user) and ignore any
client-supplied value — or reject the request if they disagree.
Database-enforced isolation¶
PostgreSQL row-level security makes the database refuse cross-tenant rows even if application code forgets the filter:
ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
ALTER TABLE invoices FORCE ROW LEVEL SECURITY; -- applies to the table owner too
CREATE POLICY tenant_isolation ON invoices
USING (tenant_id = current_setting('app.tenant_id')::uuid)
WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid);
The application sets the tenant per transaction from the verified token:
Connection pools and superusers
Use transaction-local settings (set_config(..., true) / SET LOCAL)
so a pooled connection never carries the previous request's tenant.
Application roles must not be superusers or have BYPASSRLS.
Delegation patterns¶
| Pattern | Use | Required controls |
|---|---|---|
| OAuth consent | Third-party app acts for a user | Scopes, consent screen, revocable grants |
| Token exchange (RFC 8693) | Service A calls service B on behalf of a user | New token with narrower scope/audience; act claim names the actor |
| Impersonation | Support/admin "log in as" a user | Separate permission, reason required, time-boxed, visible to the user, fully audited |
| Service accounts | Batch jobs and service-to-service calls with no user | Own identity, least privilege, short-lived credentials (workload identity), no shared human accounts |
A delegated token should always record both identities:
{
"sub": "user-123",
"act": { "sub": "support-agent-9" },
"scope": "tickets:read",
"exp": 1731958400
}
Authorization decisions use the intersection of what the subject may do and what the actor is allowed to do while delegating — and audit logs record both.
Common mistakes & mitigations¶
| Mistake | Detail | Mitigation |
|---|---|---|
| Tenant from header or path | /tenants/{id}/... trusted without comparing to the token |
Derive tenant from the token; reject mismatches |
One missed WHERE tenant_id |
A new report query returns every tenant's data | Row-level security, repository base classes that require tenant |
| Cross-tenant caches | Cache key is invoice:42, not tenant:acme:invoice:42 |
Include tenant (and subject, when relevant) in every cache key |
| Background jobs without context | Workers process jobs with no tenant set, so RLS is bypassed or broken | Carry tenant in the job payload and set it before any query |
| Impersonation with full power | "Log in as" grants everything, leaves no trace | Scoped, time-limited impersonation tokens with act and audit |
| Shared service account | Many services share one powerful credential | One identity per workload, least privilege, short-lived tokens |
| Search indexes and exports | Elasticsearch/BigQuery copies lose tenant filters | Apply tenant filters (or separate indexes) in every derived store |
When to use / avoid¶
Use
- Row-level security for any shared-table multi-tenant system
- Token exchange for any downstream call made on a user's behalf
- Dedicated, audited impersonation flows for support tooling
Avoid
- Client-supplied tenant identifiers as the source of truth
- Forwarding end-user tokens unchanged to internal services
- Long-lived, shared service-account keys
Checklist¶
- Tenant derived from the verified token on every request
- All queries tenant-scoped; row-level security as a backstop
- Cache keys, search indexes, and exports include tenant
- Background jobs carry and set tenant context
- Delegated tokens carry an
actclaim; audit logs record both identities - Impersonation requires a dedicated permission, a reason, and expires
- Each workload has its own least-privilege identity