Multi-tenant Cognito auth

Intent

This pattern assumes a SaaS serving many tenants from one deployment, behind one web app, with Amazon Cognito as its identity provider and an API gateway in front of its API. It uses one shared user pool, puts tenant access in groups, and treats the tenant claim as nothing more than the user's current choice, checked against those groups on every request. This enables three outcomes:

1. Tenant isolation never rests on a value the user can choose freely.
2. Onboarding a tenant adds a group, rather than new auth infrastructure.
3. Platform staff can work across tenants with one login, while most users hold exactly one.

Motivation

Two designs are common on multi-tenant platforms:

1. A user pool per tenant. App clients, domains and configuration multiply with every customer, and platform staff still can't have one login across tenants.
2. One pool with a free-text tenant attribute. It's cheap, but it trusts whatever that attribute says, which invites broken access control between clients.

This pattern separates choosing a tenant from being allowed into it. The attribute selects, and group membership, which only administrators can change, decides. Rebuilding the user from the token's claims in one shared place means every endpoint applies the same rules, and keying each group on an immutable reference means a client can be renamed without anyone losing access.

Applicability

Use this pattern when:

1. A SaaS serves many tenants from one deployment, behind one web app.
2. Some users, such as platform staff, need access to several tenants, and most need exactly one.
3. Tenants are onboarded often, so per-tenant auth infrastructure would multiply.

Do not use this pattern when:

1. Tenants need their own identity providers, branding or password policies.
2. A contract requires each tenant's user accounts to be held apart from the others. Keeping their data apart is a separate concern, as in database instance per tenant.

Structure

Participants

Constraints and trade-offs

1. Every request resolves groups back to tenants, which means a read each time. A cache would cut that, at the cost of serving stale access.
2. Access changes lag. A new group or role reaches the user only at their next token refresh, and AWS notes that revoked tokens stay valid for anything that only checks the signature and expiry.
3. One pool means one blast radius. A pool-wide setting or quota applies to every tenant, and tenants can't have their own sign-in policy.

Part of how I deliver

Identity is one of the first things I settle on a multi-tenant platform, because every later decision rests on it. It's one of many patterns I bring through contract delivery, and it's the base the rest of this area builds on.

Related