Role-Based Access Control (RBAC) | Bootspring Docs

Patterns for implementing role-based permissions in Next.js.

Overview#

RBAC enables granular access control:

Define user roles (admin, user, etc.)
Map permissions to roles
Protect routes and components
API endpoint authorization

Prerequisites:

User authentication system
Database with role storage

Implementation#

Role Definition#

// lib/rbac.ts
export const ROLES = {
  USER: 'USER',
  ADMIN: 'ADMIN',
  SUPER_ADMIN: 'SUPER_ADMIN'
} as const

export type Role = keyof typeof ROLES

export const PERMISSIONS = {
  // User permissions
  'user:read': [ROLES.USER, ROLES.ADMIN, ROLES.SUPER_ADMIN],
  'user:update': [ROLES.USER, ROLES.ADMIN, ROLES.SUPER_ADMIN],

  // Admin permissions
  'user:delete': [ROLES.ADMIN, ROLES.SUPER_ADMIN],
  'user:create': [ROLES.ADMIN, ROLES.SUPER_ADMIN],

  // Super admin permissions
  'admin:manage': [ROLES.SUPER_ADMIN],
  'system:configure': [ROLES.SUPER_ADMIN]
} as const

export type Permission = keyof typeof PERMISSIONS

Permission Check#

// lib/rbac.ts
import { auth } from '@/auth'
import { prisma } from '@/lib/db'

export async function getUserRole(userId: string): Promise<Role> {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    select: { role: true }
  })

  return (user?.role as Role) ?? 'USER'
}

export async function hasPermission(permission: Permission): Promise<boolean> {
  const session = await auth()
  if (!session?.user) return false

  const role = await getUserRole(session.user.id)
  return PERMISSIONS[permission].includes(role)
}

export async function requirePermission(permission: Permission) {
  const allowed = await hasPermission(permission)

  if (!allowed) {
    throw new Error('Forbidden')
  }
}

Role Guard Wrapper#

// lib/rbac.ts
export function withRole(allowedRoles: Role[]) {
  return async function guard() {
    const session = await auth()

    if (!session?.user) {
      throw new Error('Unauthorized')
    }

    const role = await getUserRole(session.user.id)

    if (!allowedRoles.includes(role)) {
      throw new Error('Forbidden')
    }

    return { session, role }
  }
}

// Usage in Server Action
export async function deleteUser(userId: string) {
  await withRole(['ADMIN', 'SUPER_ADMIN'])()

  await prisma.user.delete({ where: { id: userId } })
}

Component-Level Protection#

// components/admin-only.tsx
import { auth } from '@/auth'
import { getUserRole } from '@/lib/rbac'

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

  if (!session?.user) return null

  const role = await getUserRole(session.user.id)

  if (!['ADMIN', 'SUPER_ADMIN'].includes(role)) {
    return null
  }

  return <>{children}</>
}

API Route Protection#

// app/api/admin/users/route.ts
import { NextResponse } from 'next/server'
import { requirePermission } from '@/lib/rbac'

export async function DELETE(req: Request) {
  try {
    await requirePermission('user:delete')

    const { userId } = await req.json()
    await prisma.user.delete({ where: { id: userId } })

    return NextResponse.json({ success: true })
  } catch (error) {
    if (error.message === 'Forbidden') {
      return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
    }
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
}

Middleware-Based Protection#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { auth } from '@/auth'

const ADMIN_ROUTES = ['/admin', '/admin/(.*)']
const PROTECTED_ROUTES = ['/dashboard', '/settings']

export async function middleware(request: NextRequest) {
  const session = await auth()
  const pathname = request.nextUrl.pathname

  // Check admin routes
  if (pathname.startsWith('/admin')) {
    if (!session?.user) {
      return NextResponse.redirect(new URL('/login', request.url))
    }

    // Check for admin role
    const role = session.user.role
    if (!['ADMIN', 'SUPER_ADMIN'].includes(role)) {
      return NextResponse.redirect(new URL('/unauthorized', request.url))
    }
  }

  // Check protected routes
  if (PROTECTED_ROUTES.some(route => pathname.startsWith(route))) {
    if (!session?.user) {
      return NextResponse.redirect(new URL('/login', request.url))
    }
  }

  return NextResponse.next()
}

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

// components/nav.tsx
import { auth } from '@/auth'
import { getUserRole } from '@/lib/rbac'
import Link from 'next/link'

export async function Navigation() {
  const session = await auth()

  if (!session?.user) {
    return <PublicNav />
  }

  const role = await getUserRole(session.user.id)
  const isAdmin = ['ADMIN', 'SUPER_ADMIN'].includes(role)

  return (
    <nav>
      <Link href="/dashboard">Dashboard</Link>
      <Link href="/settings">Settings</Link>

      {isAdmin && (
        <>
          <Link href="/admin">Admin</Link>
          <Link href="/admin/users">Users</Link>
        </>
      )}

      {role === 'SUPER_ADMIN' && (
        <Link href="/admin/system">System</Link>
      )}
    </nav>
  )
}

Database Schema#

// prisma/schema.prisma
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  role      Role     @default(USER)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

enum Role {
  USER
  ADMIN
  SUPER_ADMIN
}

Usage Examples#

Protected Server Action#

// actions/admin.ts
'use server'

import { withRole } from '@/lib/rbac'
import { prisma } from '@/lib/db'
import { revalidatePath } from 'next/cache'

export async function promoteToAdmin(userId: string) {
  const { session } = await withRole(['SUPER_ADMIN'])()

  await prisma.user.update({
    where: { id: userId },
    data: { role: 'ADMIN' }
  })

  revalidatePath('/admin/users')
}

export async function deleteUser(userId: string) {
  const { session } = await withRole(['ADMIN', 'SUPER_ADMIN'])()

  // Prevent self-deletion
  if (userId === session.user.id) {
    throw new Error('Cannot delete yourself')
  }

  await prisma.user.delete({ where: { id: userId } })

  revalidatePath('/admin/users')
}

Role Check Hook (Client)#

// hooks/use-role.ts
'use client'

import { useSession } from 'next-auth/react'
import { Role, PERMISSIONS, Permission } from '@/lib/rbac'

export function useRole() {
  const { data: session } = useSession()
  const role = (session?.user?.role as Role) ?? 'USER'

  const hasPermission = (permission: Permission): boolean => {
    return PERMISSIONS[permission]?.includes(role) ?? false
  }

  const isAdmin = ['ADMIN', 'SUPER_ADMIN'].includes(role)
  const isSuperAdmin = role === 'SUPER_ADMIN'

  return {
    role,
    hasPermission,
    isAdmin,
    isSuperAdmin
  }
}

Best Practices#

Use enums for roles - Type-safe role definitions
Check permissions, not roles - More flexible access control
Default to least privilege - Users start with minimal permissions
Centralize authorization - Single source of truth for permissions
Audit role changes - Log all permission modifications

Session Management - Session handling with roles
Clerk - Clerk with role metadata
NextAuth.js - NextAuth with role callbacks