Best architecture for multi-layered RBAC in Next.js (org-level + user-level permissions)

[Im-younique]

Summary

Hello, I want to take some advice from you guys. Please give me some help and idea.

I'm building a Next.js app where each logged-in user has two separate permission layers: (1) service access granted to their organization, and (2) service access granted to the individual user. These combined permissions need to control route access, menu visibility, and component-level visibility within the same page. Currently this logic is scattered across middleware, NextAuth callbacks, per-page checks, and client-side global state — it's become messy and hard to maintain. Looking for a cleaner architectural pattern or library recommendation to centralize this.

• Two permission sources per user: org-level service access + user-level service access (need to be merged/resolved into an effective permission set)
• Need to enforce: route/middleware-level blocking, sidebar/menu item hiding, and in-page component hiding
• Currently duplicating permission checks in middleware, NextAuth session/jwt callbacks, page-level guards, and client components reading from global state
• Using NextAuth (Auth.js) — open to alternatives if it simplifies things
• Looking for: a single source of truth for computed permissions, ideas on where each layer (route vs. UI) should actually live, and any libraries (e.g., CASL, permit.io, custom hooks/HOCs) that fit well with Next.js App Router

Additional information

No response

Example

No response

[gilangabdian]

Hey, I have a thought I’d like to share:

An RBAC blueprint for the Next.js App Router.

To clean up "permission spaghetti," we need to decouple Authentication (who you are), Permission Computation/Authorization (what you can do), and Enforcement (blocking routes or hiding buttons).

This distinction is also consistent with Next.js' authentication guidance: authentication establishes identity, while authorization determines what that identity is allowed to access. ref

Here are the steps:

1. The Single Source of Truth: Core Engine

Do not use CASL or external SaaS platforms (like Permit.io) unless you need complex graph-based relationships or a compliance UI. For an Org + User matrix, a simple, pure TypeScript utility file is faster, strongly typed, and easier to maintain. Create a central permission engine that defines your actions and resolves overlaps.

Centralizing this logic also follows OWASP's guidance to use a site-wide mechanism for authorization rather than scattering access-control decisions throughout the application. ref

// types/auth.ts
export type Service = 'analytics' | 'billing' | 'ai_tools' | 'settings';
export type Action = 'view' | 'create' | 'edit' | 'delete';

export interface UserSessionData {
  orgServices: Service[];       // Tier 1: What the company paid for
  userPermissions: string[];    // Tier 2: e.g., ["analytics:view", "analytics:edit"]
}

// lib/permissions.ts
import { UserSessionData, Service, Action } from '@/types/auth';

export function createAbility(session: UserSessionData | null) {
  if (!session) {
    return { can: () => false };
  }

  // 1. Compute effective permissions by cross-referencing Org and User tiers
  const can = (service: Service, action: Action): boolean => {
    // Tier 1 Check: Does the organization even have access to this service?
    if (!session.orgServices.includes(service)) return false;

    // Tier 2 Check: Does the individual user have permission for this action?
    const requiredPermission = `${service}:${action}`;
    return session.userPermissions.includes(requiredPermission);
  };

  return { can };
}

2. NextAuth (Auth.js) Layer: Fetching the Data

Keep your NextAuth callbacks strictly focused on fetching raw data, not computing logic. I would keep the Auth.js layer responsible for authentication/session representation rather than making it the canonical authorization engine. Auth.js is primarily an authentication/session framework, while authorization can remain in a separate domain module. NextAuth should just act as the data passport. ref

// auth.ts (NextAuth v5 configuration)
import NextAuth from "next-auth";

export const { handlers, auth, signIn, signOut } = NextAuth({
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        // Fetch raw permissions from your database during login
        const dbData = await fetchUserAndOrgPermissions(user.id);
        token.orgServices = dbData.orgServices;
        token.userPermissions = dbData.userPermissions;
      }
      return token;
    },
    async session({ session, token }) {
      // Inject raw arrays into the session object
      session.user.orgServices = token.orgServices as string[];
      session.user.userPermissions = token.userPermissions as string[];
      return session;
    }
  }
});

3. Route & Page Layer: Server-Side Enforcement

Do not run complex service-level permissions inside middleware.ts. Use Proxy for coarse-grained request gating, not as the only authorization layer. Instead, use a two-step gatekeeping approach:

Step A: Proxy (The Blunt Instrument)

Use middleware only to check if a user is logged in or if they belong to a general route path (e.g., /admin/*).

// proxy.ts
export { auth as proxy } from "@/auth";

export const config = {
  matcher: ["/dashboard/:path*", "/admin/:path*"],
};

Step B: Layouts & Pages (The Scalpel)

Use Next.js Server Components to securely pull the session, run it through your central permission engine, and block access or hide layout sidebars before rendering code to the client.

// app/dashboard/analytics/page.tsx
import { auth } from "@/auth";
import { createAbility } from "@/lib/permissions";
import { redirect } from "next/navigation";
import { AnalyticsDashboard } from "@/components/AnalyticsDashboard";

export default async function AnalyticsPage() {
  const session = await auth();
  const { can } = createAbility(session?.user);

  // Secure Server-side block
  if (!can('analytics', 'view')) {
    redirect('/dashboard/unauthorized');
  }

  // Pass permissions down cleanly as basic booleans to UI
  return (
    <AnalyticsDashboard 
      canEdit={can('analytics', 'edit')} 
      canDelete={can('analytics', 'delete')} 
    />
  );
}

4. UI Layer: Sidebar & Component Visibility

To control layout sidebars and deep client buttons cleanly without prop-drilling, wrap your layout in a lightweight React Context

Provider.Step A: Create the Auth Provider

// context/PermissionContext.tsx
'use client';

import { createContext, useContext } from 'react';
import { createAbility } from '@/lib/permissions';
import { UserSessionData } from '@/types/auth';

const PermissionContext = createContext<ReturnType<typeof createAbility> | null>(null);

export function PermissionProvider({ 
  children, 
  sessionData 
}: { 
  children: React.ReactNode, 
  sessionData: UserSessionData | null 
}) {
  const ability = createAbility(sessionData);
  return (
    <PermissionContext.Provider value={ability}>
      {children}
    </PermissionContext.Provider>
  );
}

// Custom hook for client components
export function usePermission() {
  const context = useContext(PermissionContext);
  if (!context) throw new Error("usePermission must be used within PermissionProvider");
  return context;
}

Step B: Inject at the Dashboard Root Layout

// app/dashboard/layout.tsx
import { auth } from "@/auth";
import { PermissionProvider } from "@/context/PermissionContext";
import { Sidebar } from "@/components/Sidebar";

export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
  const session = await auth();

  return (
    <PermissionProvider sessionData={session?.user || null}>
      <div className="flex">
        <Sidebar />
        <main>{children}</main>
      </div>
    </PermissionProvider>
  );
}

Step C: Hide Elements in the UI

This is a presentation concern, not a security boundary. Hiding a button or sidebar item improves UX, but a user can still manually call the underlying endpoint. OWASP explicitly warns against relying on client-side access-control checks. ref

Now, any client-side sidebar link or nested button can call the exact same can() engine directly, keeping the UI consistent with the same authorization policy.

// components/Sidebar.tsx (Client Component)
'use client';

import { usePermission } from "@/context/PermissionContext";
import Link from "next/link";

export function Sidebar() {
  const { can } = usePermission();

  return (
    <nav>
      {can('analytics', 'view') && <Link href="/dashboard/analytics">Analytics</Link>}
      {can('ai_tools', 'view') && <Link href="/dashboard/ai">AI Toolkit</Link>}
      {can('settings', 'view') && <Link href="/dashboard/settings">Settings</Link>}
    </nav>
  );
}

Summary Checklist of this Architecture

1. No Logic Duplication: The resolution code (orgServices × userPermissions) lives exclusively in lib/permissions.ts.
2. Coarse Proxy: Use Proxy for inexpensive, coarse-grained request gating such as authentication or broad route groups. Keep fine-grained authorization in the shared server-side authorization layer. Next.js demonstrates Proxy being used to protect authenticated dashboard routes.
3. Server First: Page-level checks can prevent unauthorized UI from rendering, but authorization must also be enforced at the server-side operation boundary (Server Actions, Route Handlers, APIs, or data-access layer). Client-side visibility is only UX.
4. Snappy Client UI: The layout context handles conditional rendering (can('service', 'action')) for sidebars and granular buttons smoothly.

Don't try to make one layer do everything. Make one authorization policy the source of truth, and let different layers consume that policy for different purposes.

[Im-younique]

Thanks for such a solid, back-to-basics answer! I'll go through the principles one by one and start stripping out the extra logic in my codebase.

One more question — I think one thing I was missing is that there's actually another layer in my case: the backend team enforces RBAC conventions that also dictate the actual menu/route paths themselves (not just view/edit-level permissions, but the routes are defined and constrained by the backend RBAC contract). I suspect not accounting for this layer properly is part of why things got messy in the first place. Is there a cleaner way to handle this kind of backend-driven route enforcement on top of the architecture you described?

It's a bit sad that trying to push control down into so many layers ended up creating more of a spaghetti mess instead of less.

[gilangabdian]

Thanks! I think you've identified an important extra dimension: the backend route/RBAC contract should probably be treated as an input to the authorization architecture, rather than creating another independent permission layer in the frontend.

If the backend is authoritative about both:

permission → resource → route

I'd avoid maintaining a separate frontend mapping like:

analytics:view → /dashboard/analytics
billing:view   → /dashboard/billing

in multiple places. That's where the spaghetti can come back.

Instead, I'd think about the architecture as:

Backend RBAC Contract
        │
        ├── permissions
        └── resource/route definitions
                 │
                 ▼
        Frontend policy/route layer
                 │
        ┌────────┼────────┐
        ↓        ↓        ↓
      Proxy    Server     UI
      gating  enforcement visibility

The important distinction is that these layers consume the same policy, rather than independently implementing authorization.

For example, you could have a single resource registry:

const routes = {
  analytics: {
    path: "/dashboard/analytics",
    permission: ["analytics", "view"],
  },
  billing: {
    path: "/dashboard/billing",
    permission: ["billing", "view"],
  },
} as const;

Then the sidebar, links, and route checks can all derive from that definition instead of each having its own permission → route mapping.

If the backend already exposes this contract through something like OpenAPI or another schema, I'd go one step further and generate the TypeScript representation from the backend contract rather than manually duplicating it in the frontend. That gives you a much cleaner boundary:

Backend contract
      ↓
generated types/metadata
      ↓
frontend authorization layer
      ↓
Proxy / Server / UI

This also fits fairly well with the current Next.js guidance. Next.js recommends centralizing authorization in a Data Access Layer, while treating Proxy as an optional optimistic check rather than the complete authorization solution. It also recommends enforcing authorization close to the data source. ref, ref

And Route Handlers should be treated as public endpoints, so if the Next.js app is sitting in front of the backend, the actual backend/Route Handler still needs to enforce authorization rather than trusting the frontend route or UI state. ref

So I don't think the lesson is necessarily "fewer layers." I'd say it's:

Many enforcement points are okay; many sources of authorization truth are not.

The backend can remain authoritative about the resource/route contract, while the frontend has one policy layer that translates that contract into the things Proxy, Server Components/Actions, and UI need.

That separation might make the system considerably less messy without fighting the backend team's RBAC conventions.

[Im-younique]

Thanks, I got some idea from you!!
I really appreciate it :)