Multi Tenant Auth: Mermaid Flowchart Diagram

About Source

Multi-tenant authentication is the architecture pattern used by SaaS applications to authenticate users from many different customer organizations ("tenants"), each potentially using a different identity system, while keeping their data and identities strictly isolated from one another.

The central challenge is tenant resolution: when a request arrives, the system must determine which tenant the user belongs to before it can authenticate them. Common resolution strategies include subdomain-based routing (acme.yourapp.com routes to the Acme tenant), a login-time domain lookup (the user enters their email and the system derives the tenant from the domain), or an explicit tenant ID in the URL path.

Once the tenant is identified, the authentication configuration for that tenant is loaded. Each tenant may have its own configuration: some tenants use username/password with your app's built-in auth; others bring their own identity provider via SAML Authentication Flow or OpenID Connect Flow (enterprise SSO); others may authenticate via Social Login Flow. The authentication engine routes accordingly.

After authentication, tenant context is embedded in the session or access token — typically a tenant_id claim in a JWT. Every subsequent authorization decision, data query, and audit log entry is scoped to this tenant ID. Middleware enforces that users can only access resources belonging to their own tenant, even if they somehow obtain a valid token intended for another tenant.

Role and permission structures in multi-tenant systems are per-tenant: Tenant A's admin role may have completely different permissions than Tenant B's admin role. The data modeling for this is shown in Role Hierarchy Structure. The overall access decision process is covered in Access Control Decision Flow.

Frequently asked questions

Multi-tenant authentication is the pattern SaaS applications use to authenticate users from many different customer organisations, each potentially using a different identity system, while keeping their data and identities strictly isolated. The same application serves all tenants, but each tenant's authentication configuration, users, and permissions are completely separate.

Tenant resolution determines which tenant a user belongs to before authentication begins. Common strategies are subdomain routing (`acme.yourapp.com` maps to the Acme tenant), email domain lookup (the user enters their email and the system derives the tenant from the domain), or an explicit tenant identifier in the URL path. The resolved tenant ID determines which authentication configuration — built-in, SAML, or OIDC — is loaded.

After authentication, a `tenant_id` claim is embedded in the session or JWT. Every authorization check, database query, and audit log entry is scoped to this tenant ID. Middleware validates that the resource being requested belongs to the same tenant as the authenticated user — this must be enforced even for users with valid tokens, to prevent cross-tenant data access.

Each tenant can be configured independently: some tenants use username/password with the application's built-in auth, others bring their own IdP via SAML 2.0 (common in regulated enterprises) or OpenID Connect (common in tech companies using Okta, Azure AD, or Google Workspace). A well-designed multi-tenant auth system supports all three configurations simultaneously and routes authentication requests accordingly based on the resolved tenant.

The most critical risk is cross-tenant data leakage — a user from Tenant A accessing Tenant B's data. This is prevented by consistently scoping all operations to `tenant_id`. Other risks include tenant resolution bypass (manipulating the subdomain or email to be routed to another tenant's IdP), JWT `tenant_id` claim tampering (mitigated by signature verification), and improperly shared session stores that bleed session data across tenants.

mermaid

flowchart TD
    REQ([Incoming login request]) --> RESOLVE{Resolve tenant}
    RESOLVE -- Subdomain: acme.app.com --> T1[Tenant: Acme Corp]
    RESOLVE -- Email domain: user@beta.io --> T2[Tenant: Beta Inc]
    RESOLVE -- URL path: /org/gamma --> T3[Tenant: Gamma LLC]

    T1 --> T1_CONFIG[Load Tenant A auth config]
    T2 --> T2_CONFIG[Load Tenant B auth config]
    T3 --> T3_CONFIG[Load Tenant C auth config]

    T1_CONFIG --> T1_TYPE{Auth method}
    T1_TYPE -- SAML SSO --> SAML[Redirect to Acme IdP]
    T1_TYPE -- OIDC SSO --> OIDC[Redirect to Acme OIDC Provider]

    T2_CONFIG --> T2_TYPE{Auth method}
    T2_TYPE -- Built-in password --> LOCAL[Username + password login]

    T3_CONFIG --> T3_TYPE{Auth method}
    T3_TYPE -- Social login --> SOCIAL[OAuth2 provider redirect]

    SAML --> TOKEN[Issue JWT with tenant_id claim]
    OIDC --> TOKEN
    LOCAL --> TOKEN
    SOCIAL --> TOKEN

    TOKEN --> ENFORCE[Middleware enforces tenant isolation]
    ENFORCE --> ACCESS([Access scoped to tenant data only])