Multi-tenant authentication: what has to be isolated, and how

Multi-tenant authentication is the part of a B2B product that looks easy on the whiteboard — "just add a tenant ID" — and gets hard when the first enterprise customer asks for their own SSO, their own user directory and their own audit trail.

This article covers the models, what has to be isolated, and how per-tenant SSO and provisioning fit in.

The three models

1. Shared deployment, logical tenants. One identity service holds every tenant's users, separated by an organization or tenant ID. Cheapest to run and easiest to upgrade; isolation is enforced by the application and the data model.

2. Shared service, per-tenant configuration. One service, but each tenant has its own applications, identity provider connections, branding and signing keys. This is what most B2B SaaS actually needs: one deployment, many isolated configurations.

3. Dedicated deployment per tenant. Each customer gets its own instance and database. Maximum isolation, and the highest operational cost. This is what regulated customers often ask for, and what a managed identity provider can offer as a per-instance plan.

The right answer is usually a mix: model 2 for most customers, model 3 for the ones who require it.

What must be isolated

• Users and credentials. A user in tenant A must never resolve in tenant B, even with the same email.
• Sessions and tokens. A token issued for one tenant must not be accepted by another; put the tenant in the audience or a claim and validate it.
• Identity provider connections. Each tenant's SAML or OIDC settings are theirs: entity ID, certificate, attribute mapping.
• Signing keys and domains. If tenants use custom domains, each domain needs its own certificate and branding.
• Branding and email templates. The login page is often the most visible part of a tenant's product.
• Audit logs. Each tenant's admins should see their own events, not everyone's.

The common failure is treating tenancy as a filter on queries. It has to be part of the token and the session, or one missed filter becomes a cross-tenant data leak.

Per-tenant B2B SSO

Enterprise customers expect to bring their own identity provider. In a multi-tenant system that means:

• Each tenant stores its own SAML or OIDC connection.
• The login page routes by email domain or tenant slug to the right connection.
• A customer's users sign in through their IdP, and the assertion maps to a user inside that tenant only.
• Local passwords may be disabled for that tenant entirely.

This is the single most requested multi-tenant feature, and the one most often hacked in as a special case. Model it as tenant configuration from the start.

Per-tenant provisioning

When a customer connects their IdP, they usually want SCIM next:

• Their identity provider creates users in your tenant through a SCIM endpoint scoped to that tenant.
• Deactivation in their directory deactivates the account in yours.
• Group membership maps to roles inside that tenant.

A SCIM endpoint that is not tenant-scoped is a security incident waiting for a token leak. Scope every SCIM request to the tenant that owns the credentials.

Authorization within a tenant

Isolation is only half the model. Inside a tenant, users need roles and permissions:

• A tenant administrator who can manage users and connections.
• Application roles that come from the customer's directory groups.
• Permissions that map to your product's features.

Keep the tenant boundary and the role model separate: the tenant decides where a user exists, roles decide what they can do there.

How Casdoor models it

Casdoor uses organizations as the tenant boundary. Users, applications and identity provider connections belong to an organization; an application has its own client credentials, redirect URLs and branding. That maps to model 2 above.

• Self-hosted, the number of organizations is unlimited.
• Casdoor Cloud gives each customer a dedicated instance and database; the Basic plan includes 1 organization, Premium 10, Enterprise unlimited, with a custom domain from Premium up.

That combination is useful for the mixed case: most customers share a deployment, and the ones who need a dedicated instance get one with the same software.

See organizations and applications in the docs.

A checklist for the design review

1. Is the tenant part of the token, not just the database row?
2. Can one tenant's IdP configuration affect another's login?
3. Are SCIM credentials scoped to a single tenant?
4. Do audit logs separate tenants?
5. Can a tenant be deleted completely, including users and keys?
6. Is there a path from shared to dedicated for the customers who demand it?

Related reading: SSO for SaaS, add SSO to your app and SCIM vs SAML.

Casdoor is open source and self-hostable, with a hosted option from $9 per month and no per-user fees.