Multi-Tenant SaaS Portals on Next.js: Managing Auth, Routing, and Dynamic Subdomains

flowchart TD
    Client["Client Browser<br/>(acme.saas.live/dashboard)"] -->|HTTPS Request| Cloudflare["Edge CDN / Wildcard TLS<br/>(.saas.live & Custom CNAMEs)"]
    
    subgraph Edge_Tier ["Next.js Edge Middleware Layer (Sub-15ms)"]
        Cloudflare -->|Host: acme.saas.live| Middleware["Next.js Edge Middleware<br/>(middleware.ts)"]
        Middleware -->|Subdomain / Host Extract| TenantResolver["Tenant Lookup Cache<br/>(Edge Redis / Upstash)"]
        TenantResolver -.->|Tenant Context: org_123| Middleware
        Middleware -->|"NextResponse.rewrite() (Internal)"| InternalRoute["Internal Dynamic App Route<br/>(/_tenants/[tenant]/dashboard)"]
    end
    subgraph App_Tier ["Next.js App Router Server Components"]
        InternalRoute --> ServerComponent["React Server Component<br/>(Auth & Context Verification)"]
        ServerComponent -->|Verify JWT Claims| AuthGuard["Tenant Session Guard<br/>(session.activeOrg == org_123)"]
    end
    subgraph Data_Tier ["Tenant-Isolated Persistence Tier"]
        AuthGuard -->|Checkout Pooled DB Socket| PgBouncer["PgBouncer Connection Pooler<br/>(Transaction Mode)"]
        PgBouncer -->|SET LOCAL app.current_tenant_id| Postgres["PostgreSQL 16 Engine<br/>Row-Level Security (RLS) Active"]
        Postgres -->|Automatic Row Filtering| QueryExecution["Isolated Result Set<br/>(Zero Cross-Tenant Leakage)"]
    end
    QueryExecution -.->|Stream Server HTML| Client

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|               END-TO-END MULTI-TENANT REQUEST LIFECYCLE & RESOLUTION                            |
+─────────────────────────────────────────────────────────────────────────────────────────────────+
|                                                                                                 |
|   [Client Request: https://acme.saas.live/dashboard/billing]                                    |
|         │                                                                                       |
|         ▼                                                                                       |
|   [Edge CDN / Wildcard Ingress: .saas.live + Custom Enterprise CNAMEs]                         |
|         │                                                                                       |
|         ▼                                                                                       |
|   [Next.js Edge Middleware]                                                                     |
|         │ 1. Extract Host: "acme.saas.live"                                                     |
|         │ 2. Sub-5ms Tenant Resolution (Edge Redis Cache)                                       |
|         ▼                                                                                       |
|   [Transparent Internal Rewrite: /_tenants/acme/dashboard/billing]                              |
|   (Browser URL remains strictly "acme.saas.live/dashboard/billing")                             |
|         │                                                                                       |
|         ▼                                                                                       |
|   [React Server Component Ingestion]                                                            |
|         │ • Verify Session: Ensure JWT user belongs to tenant "org_acme_123"                    |
|         │ • Propagate request-scoped tenant context via React cache()                           |
|         ▼                                                                                       |
|   [PostgreSQL Transaction Boundary]                                                             |
|         │ BEGIN;                                                                                |
|         │ SET LOCAL app.current_tenant_id = 'org_acme_123';                                     |
|         │ SELECT  FROM invoices WHERE status = 'unpaid';                                       |
|         │ COMMIT;                                                                               |
|         ▼                                                                                       |
|   [Row-Level Security Policy: Automatically filters rows where tenant_id = 'org_acme_123']      |
|         │                                                                                       |
|         ▼                                                                                       |
|   [Rendered HTML Stream Delivered to Client with Sub-50ms TTFB]                                 |
|                                                                                                 |
+─────────────────────────────────────────────────────────────────────────────────────────────────+

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|                     MULTI-TENANCY PERSISTENCE ARCHITECTURE COMPARISON                           |
+──────────────────────────+──────────────────────+───────────────────────+───────────────────────+
| Dimension                | Database-per-Tenant  | Schema-per-Tenant     | Shared DB with RLS    |
+──────────────────────────+──────────────────────+───────────────────────+───────────────────────+
| Physical Isolation       | Complete (Hard)      | Logical (Namespaced)  | Logical (Row-Level)   |
| Infrastructure Overhead  | Extreme (High Cost)  | Moderate (RAM Heavy)  | Minimal (Optimal)     |
| Schema Migrations        | N Migrations (Slow)  | N Schemas (Catalog)   | 1 Single Migration    |
| Connection Pool Scaling  | Exhausts Sockets     | Moderate Contention   | Maximum Pool Reuse    |
| Max Tenants on Node      | 50 - 200             | 500 - 2,000           | 50,000+               |
| Blast Radius Risk        | Zero                 | Minimal               | Requires Strict RLS   |
| Compliance (FedRAMP/SOC) | Easiest to Audit     | Moderate              | Standard with Auditing|
+──────────────────────────+──────────────────────+───────────────────────+───────────────────────+

  // src/middleware.ts
  import { NextRequest, NextResponse } from "next/server";
  // Reserved subdomains that map to core application services
  const RESERVED_SUBDOMAINS = new Set(["app", "api", "auth", "admin", "staging", "billing"]);
  const ROOT_DOMAIN = process.env.NEXT_PUBLIC_ROOT_DOMAIN || "knetwork.live";
  export const config = {
    matcher: [
      // Match all request paths except static files, _next, and favicon
      "/((?!api/|_next/|_static/|[\\w-]+\\.\\w+).)",
    ],
  };
  export default async function middleware(req: NextRequest) {
    const url = req.nextUrl;
    const hostname = req.headers.get("host") || "";
    // 1. Normalize hostname (remove port numbers in local development)
    const cleanHost = hostname.split(":")[0].toLowerCase();
    // 2. Identify Root vs. Subdomain vs. Custom Enterprise Domain
    let tenantIdentifier: string | null = null;
    let isCustomDomain = false;
    if (cleanHost === ROOT_DOMAIN || cleanHost === www.${ROOT_DOMAIN}) {
      // Root marketing domain -> serve standard public marketing routes
      return NextResponse.next();
    } else if (cleanHost.endsWith(.${ROOT_DOMAIN})) {
      // Subdomain extraction: "acme.knetwork.live" -> "acme"
      const subdomain = cleanHost.replace(.${ROOT_DOMAIN}, "");
      
      if (RESERVED_SUBDOMAINS.has(subdomain)) {
        // App portal route -> rewrite to internal app handler
        return NextResponse.rewrite(new URL(/app${url.pathname}${url.search}, req.url));
      }
      
      tenantIdentifier = subdomain;
    } else {
      // Custom Enterprise Domain (e.g. portal.acmewidgets.com)
      isCustomDomain = true;
      tenantIdentifier = await resolveCustomDomainToTenant(cleanHost);
      if (!tenantIdentifier) {
        // Unmapped custom domain -> redirect to domain setup guide
        return NextResponse.redirect(new URL("/domain-not-configured", req.url));
      }
    }
    // 3. Inject Tenant Headers for Downstream Server Components
    const requestHeaders = new Headers(req.headers);
    requestHeaders.set("x-tenant-slug", tenantIdentifier);
    requestHeaders.set("x-is-custom-domain", isCustomDomain ? "1" : "0");
    requestHeaders.set("x-current-path", url.pathname);
    // 4. Transparent Internal Path Rewrite
    // Maps "https://acme.knetwork.live/billing" -> "/_tenants/acme/billing"
    const rewriteUrl = new URL(
      /_tenants/${tenantIdentifier}${url.pathname}${url.search},
      req.url
    );
    return NextResponse.rewrite(rewriteUrl, {
      request: {
        headers: requestHeaders,
      },
    });
  }
  /*
    Resolve custom enterprise domain CNAME via Edge-cached Redis lookup
    Latency ceiling: < 5ms
   /
  async function resolveCustomDomainToTenant(domain: string): Promise<string | null> {
    try {
      const edgeCacheUrl = ${process.env.EDGE_KV_REST_API_URL}/get/domain:${domain};
      const res = await fetch(edgeCacheUrl, {
        headers: { Authorization: Bearer ${process.env.EDGE_KV_REST_API_TOKEN} },
        next: { revalidate: 300 }, // Cache resolution at Edge for 5 minutes
      });
      if (!res.ok) return null;
      const data = await res.json();
      return data.result || null;
    } catch (e) {
      console.error("Custom domain resolution failure:", e);
      return null;
    }
  }

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|               CUSTOM ENTERPRISE DOMAIN VERIFICATION & TLS FLOW                                  |
+─────────────────────────────────────────────────────────────────────────────────────────────────+
|                                                                                                 |
|   1. Customer Adds CNAME: portal.acme.com ──► cname.knetwork.live                               |
|   2. Next.js Verification Endpoint checks DNS TXT record for domain ownership verification.     |
|   3. System issues API call to Edge Proxy (Cloudflare for SaaS / AWS CloudFront)               |
|      to provision automated Let's Encrypt Wildcard TLS certificate.                             |
|   4. Edge KV Cache updated: domain:portal.acme.com ──► tenant_slug: "acme"                     |
|                                                                                                 |
+─────────────────────────────────────────────────────────────────────────────────────────────────+

  // src/app/api/domains/verify/route.ts
  import { NextRequest, NextResponse } from "next/server";
  import dns from "dns/promises";
  import { Redis } from "@upstash/redis";
  const redis = Redis.fromEnv();
  export async function POST(req: NextRequest) {
    const { domain, tenantSlug, verificationToken } = await req.json();
    // 1. Verify TXT challenge record: _knetwork-challenge.portal.acme.com
    try {
      const txtRecords = await dns.resolveTxt(_knetwork-challenge.${domain});
      const isVerified = txtRecords.some((record) => record.includes(verificationToken));
      if (!isVerified) {
        return NextResponse.json({ error: "Verification token mismatch" }, { status: 400 });
      }
      // 2. Register domain with Edge TLS Provider (e.g. Cloudflare for SaaS API)
      const cfRes = await fetch(
        https://api.cloudflare.com/client/v4/zones/${process.env.CF_ZONE_ID}/custom_hostnames,
        {
          method: "POST",
          headers: {
            "Authorization": Bearer ${process.env.CF_API_TOKEN},
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            hostname: domain,
            ssl: { method: "http", type: "dv" },
          }),
        }
      );
      // 3. Store routing link in Edge Redis
      await redis.set(domain:${domain}, tenantSlug);
      return NextResponse.json({ verified: true, domain, tenantSlug });
    } catch (error: any) {
      return NextResponse.json({ error: "DNS record not found", details: error.message }, { status: 404 });
    }
  }

{
  "sub": "usr_99842a17",
  "email": "sarah.lead@acme.com",
  "activeTenant": {
    "id": "org_c41e882a",
    "slug": "acme",
    "role": "TENANT_ADMIN",
    "permissions": ["invoices:read", "invoices:write", "members:invite"]
  },
  "availableTenants": ["org_c41e882a", "org_98771bc2"],
  "iat": 1727145600,
  "exp": 1727232000
}

  // src/lib/tenant-context.ts
  import { cache } from "react";
  import { headers } from "next/headers";
  import { auth } from "@/lib/auth"; // Auth.js / NextAuth session
  import { db } from "@/lib/db";
  export interface TenantContext {
    id: string;
    slug: string;
    name: string;
    role: string;
    isCustomDomain: boolean;
  }
  /*
    Request-scoped tenant context resolver.
    Cached for the duration of a single HTTP request lifecycle.
   /
  export const getTenantContext = cache(async (): Promise<TenantContext> => {
    const headersList = headers();
    const routeSlug = headersList.get("x-tenant-slug");
    const isCustomDomain = headersList.get("x-is-custom-domain") === "1";
    if (!routeSlug) {
      throw new Error("Tenant context missing from edge headers");
    }
    // 1. Validate authenticated session
    const session = await auth();
    if (!session || !session.user) {
      throw new Error("Unauthorized request");
    }
    // 2. Fetch tenant profile from DB or cache
    const tenant = await db.tenant.findUnique({
      where: { slug: routeSlug },
      select: { id: true, slug: true, name: true },
    });
    if (!tenant) {
      throw new Error("Tenant organization not found");
    }
    // 3. Strict Cross-Tenant Guard: Verify user belongs to this tenant
    const membership = await db.tenantMember.findUnique({
      where: {
        userId_tenantId: {
          userId: session.user.id,
          tenantId: tenant.id,
        },
      },
      select: { role: true },
    });
    if (!membership) {
      // User is logged in, but has no access to this specific organization
      throw new Error("Forbidden: Access denied to this tenant portal");
    }
    return {
      id: tenant.id,
      slug: tenant.slug,
      name: tenant.name,
      role: membership.role,
      isCustomDomain,
    };
  });

flowchart LR
    subgraph Application_Call ["Next.js Server Execution"]
        App["Server Action / Query<br/>SELECT  FROM customer_invoices;"]
    end
    subgraph Pooler ["Connection Multiplexer"]
        PgB["PgBouncer Pooler<br/>(Transaction Mode)"]
    end
    subgraph DB_Kernel ["PostgreSQL 16 Engine"]
        Session["Session Context Initialization<br/>SET LOCAL app.current_tenant_id = 'org_123'"]
        Engine["Query Planner & Executor"]
        RLS{"Row-Level Security Policy<br/>tenant_id = current_setting()"}
        Table[("customer_invoices Table<br/>[Rows for org_123, org_456, org_789]")]
    end
    App --> PgB
    PgB --> Session
    Session --> Engine
    Engine --> RLS
    RLS --> Table
    Table -->|"Returns ONLY org_123 Rows"| Engine
    Engine -->|"Zero Cross-Tenant Leakage"| App

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|               POSTGRESQL ROW-LEVEL SECURITY ENFORCEMENT ENGINE                                  |
+─────────────────────────────────────────────────────────────────────────────────────────────────+
|                                                                                                 |
|   1. Application Client connects to PgBouncer:                                                  |
|      BEGIN;                                                                                     |
|      SET LOCAL app.current_tenant_id = 'c41e882a-0000-0000-0000-000000000000';                 |
|                                                                                                 |
|   2. Application executes naive query without tenant filter:                                    |
|      SELECT invoice_id, amount, client_name FROM invoices;                                      |
|                                                                                                 |
|   3. PostgreSQL Kernel evaluates RLS Policy:                                                    |
|      POLICY: tenant_isolation_policy ON invoices                                                |
|      USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid);      |
|                                                                                                 |
|   4. Physical Table Scan:                                                                       |
|      Row 1: [Tenant: c41e882a] ──► MATCH    ──► Returned to App                                 |
|      Row 2: [Tenant: 98771bc2] ──► MISMATCH ──► Filtered Out by Engine Kernel                   |
|      Row 3: [Tenant: 12345678] ──► MISMATCH ──► Filtered Out by Engine Kernel                   |
|                                                                                                 |
|   5. COMMIT; ──► Session variable automatically wiped when transaction concludes.              |
|                                                                                                 |
+─────────────────────────────────────────────────────────────────────────────────────────────────+

  -- 1. Enable Row-Level Security on tenant data tables
  ALTER TABLE organizations ENABLE ROW LEVEL SECURITY;
  ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
  ALTER TABLE audit_logs ENABLE ROW LEVEL SECURITY;
  -- 2. Create the RLS Isolation Policy for Invoices
  -- current_setting('app.current_tenant_id', true) retrieves the session variable.
  -- Setting parameter 'true' returns NULL instead of erroring if uninitialized.
  CREATE POLICY tenant_isolation_invoices ON invoices
    FOR ALL
    USING (
      tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid
    )
    WITH CHECK (
      tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid
    );
  -- 3. Superuser bypass prevention:
  -- Ensure application database user (e.g. "saas_app_user") is NOT a PostgreSQL superuser,
  -- as superusers automatically bypass RLS rules.
  ALTER TABLE invoices FORCE ROW LEVEL SECURITY;

  // src/lib/db-tenant-client.ts
  import { Pool, PoolClient } from "pg";
  import { getTenantContext } from "@/lib/tenant-context";
  const pool = new Pool({
    connectionString: process.env.DATABASE_URL, // Points to PgBouncer port 6432
    max: 40,
  });
  /*
    Execute a database query within a strictly scoped tenant transaction.
   /
  export async function withTenantDb<T>(
    operation: (client: PoolClient) => Promise<T>
  ): Promise<T> {
    const tenant = await getTenantContext();
    const client = await pool.connect();
    try {
      await client.query("BEGIN");
      // Scope session variable strictly to this transaction
      // SET LOCAL automatically resets on COMMIT / ROLLBACK
      await client.query("SET LOCAL app.current_tenant_id = $1", [tenant.id]);
      const result = await operation(client);
      await client.query("COMMIT");
      return result;
    } catch (error) {
      await client.query("ROLLBACK");
      throw error;
    } finally {
      client.release();
    }
  }