Next.js 16 앱에서 Auth.js v5와 Prisma를 조합해 3단계 역할 기반 접근제어 시스템 구현

Context

SaaS 애플리케이션이 성장하면서 단일 사용자 타입에서 팀 플랜, 관리자 대시보드, 읽기 전용 게스트 모드 등 다양한 역할을 지원해야 하는 요구사항이 발생한다. 역할 기반 접근제어(RBAC)가 없으면 이러한 기능을 체계적으로 관리하기 어렵다.

Technical Solution

• Prisma 스키마에 UserRole enum(USER, ADMIN, VIEWER) 추가: 데이터베이스 마이그레이션으로 User 모델에 role 필드를 기본값 USER로 설정
• Auth.js v5 세션 콜백 확장: session 객체에 user.role 필드를 명시적으로 추가하고 TypeScript 타입 선언 파일(next-auth.d.ts)에서 User와 Session 인터페이스 확장
• Next.js 미들웨어를 통한 페이지 보호: /dashboard/* 경로에 미들웨어를 적용해 미인증 사용자는 /login으로 리다이렉트, /dashboard/admin/* 경로는 ADMIN 역할만 접근 허용
• API 라우트 보호 헬퍼 함수 생성: requireRole() 함수로 세션을 확인하고 역할 검증, 미일치 시 401(Unauthorized) 또는 403(Forbidden) 응답 반환
• 서버/클라이언트 컴포넌트에서 조건부 렌더링: 서버 컴포넌트에서 auth()로 세션 읽기, 클라이언트 컴포넌트에서 useSession() 훅으로 역할 확인 후 UI 조건부 표시

Key Takeaway

Auth.js v5, Prisma, Next.js 미들웨어를 조합하면 데이터베이스 레벨 역할 관리부터 엣지(Edge)에서의 페이지 보호, API 라우트 검증, UI 렌더링까지 일관된 RBAC 시스템을 구축할 수 있다. 클라이언트 측 역할 확인은 UX용이며, 보안을 위해서는 항상 서버 측(미들웨어 또는 API 라우트)에서 역할을 강제 검증해야 한다.