Auth, permissions and multi-tenancy

Authentication (authN) answers 'who are you?'. Users log in with a password, OTP, passkey or a social or enterprise identity provider; services prove their identity with mTLS certificates or signed tokens. The result is usually a short-lived token, such as a JWT access token, or a session ID stored server-side.

Authorisation (authZ) answers 'what may you do?'. Common models: RBAC (roles like admin, editor, viewer), ABAC (rules on attributes: 'managers can approve expenses under Rs 50,000 in their own department'), and ReBAC (relationships: 'you can view a document if you are a member of a team that owns its folder'), popularised by Google's Zanzibar.

Multi-tenancy means one system serves many customer organisations (tenants). Isolation can be silo (separate database or stack per tenant), pool (shared tables with a tenant_id column) or bridge (shared app, separate schemas or databases for large tenants). Most SaaS products pool small tenants for cost and move large or regulated ones into silos. The core rule: tenant ID comes from the authenticated identity, never from a request parameter, and it is enforced at every layer.

1. 1Use a standard identity layer: OAuth 2.0 for delegated access and OpenID Connect (OIDC) for login, through an identity provider such as Keycloak, Auth0, Cognito or your own service. For enterprise tenants support SAML or OIDC single sign-on.
2. 2Issue short-lived access tokens (5-15 minutes) and longer refresh tokens (days to weeks) that are rotated on each use and stored securely. Mobile apps use the authorisation code flow with PKCE.
3. 3Verify tokens at the API gateway (signature, expiry, audience, issuer) using the provider's public keys (JWKS), and pass the verified identity (user_id, tenant_id, roles) to services. Services still check permissions for the specific resource.
4. 4Understand the JWT trade-off: verification is stateless and fast, but a stolen or revoked token stays valid until it expires. Keep expiry short, keep a small deny-list for emergencies, or use opaque tokens checked against a session store when instant revocation is required.
5. 5Authenticate service-to-service calls too: mTLS inside a service mesh (Istio, Linkerd, SPIFFE identities) or signed service tokens, so a compromised pod cannot call everything.
6. 6Model authorisation for the product: RBAC for simple admin features; ReBAC or ABAC for sharing (documents, folders, projects). Centralise policy in a service or library (OpenFGA, SpiceDB, Open Policy Agent, Cedar) so rules are consistent and auditable.
7. 7Carry tenant_id in every row, every cache key, every search and vector index filter, every object storage path and every log line. Partition or shard large tables by tenant_id.
8. 8Enforce tenant isolation in the database as a second line of defence, for example Postgres row-level security with a per-transaction tenant setting, and an app role that is not the table owner.
9. 9Limit noisy neighbours: per-tenant rate limits, quotas, connection limits and LLM token budgets; move very large tenants to dedicated shards or silos.
10. 10Audit: log every permission change and sensitive access with who, what, when and tenant; enterprise customers will ask for these logs.

-- Every tenant table carries tenant_id and has RLS enforced.
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE documents FORCE ROW LEVEL SECURITY;  -- applies to the table owner too

CREATE POLICY tenant_isolation ON documents
  USING (tenant_id = current_setting('app.tenant_id')::uuid)
  WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid);

-- Per request, inside the transaction (app connects as a non-owner role):
BEGIN;
SET LOCAL app.tenant_id = '6f1c2a9e-0000-4000-8000-000000000001';
SELECT id, title FROM documents WHERE folder_id = $1;  -- only this tenant's rows
COMMIT;