Multi-tenant authentication: signing in many customers safely

Every B2B SaaS eventually has to answer: how do you guarantee that a user from Company A never sees Company B’s data — including tokens, sessions, permissions, and login settings? Multi-tenant authentication is not just putting a tenant_id in the URL. It is isolating identity end to end.

Common isolation models

Shared database, shared schema

One database; every row carries a tenant id. Cheaper, and it demands strict discipline in queries and tokens — one bug becomes a cross-tenant leak.

A realm or tenant per customer (IAM)

Each customer has its own realm or namespace in the identity provider. Users, OAuth clients, and policies stay separate. Keycloak and Gatekeeper ID follow this line.

Dedicated instance

Enterprise customers with an isolated stack. Maximum isolation, high operating cost — rare at the start.

Problems that show up early

• Discovering the tenant at login (subdomain, header, email domain?)
• Propagating tenant id in the JWT, logs, and traces
• Social login with a redirect URI and an OAuth client per tenant
• Different RBAC per customer in the same codebase
• Migrations and backups that do not mix data

Practices that hold

• Include tenant_id (or an equivalent claim) in the signed token — do not trust only an HTTP header from the client
• Validate the tenant at the gateway and again in the service (defense in depth)
• An admin console separated by tenant, or with an explicit scope
• Audit with tenant id on every login and permission change
• Automated isolation tests — not only functional tests

Common mistakes

• One OAuth client for every tenant
• A JWKS or session cache with no per-tenant key
• A super-admin with no audit trail
• Allowing the tenant id to be swapped in the request body after login

How Gatekeeper ID helps

Each Gatekeeper tenant gets an isolated Keycloak realm, its own API keys, and a console to manage users and permissions. The SDK sends X-GK-Tenant-ID and validates tokens in the right context — you integrate once and onboard customers from the console.

Compare approaches in Keycloak vs Gatekeeper.

Conclusion

Multi-tenant authentication is an architecture requirement, not a login feature. The earlier you isolate identity per customer, the lower the cost of refactoring when the first enterprise customer arrives.