Next.js Auth (Auth.js v5)

Next.js 인증 (Auth.js v5)

규칙

1. 구성은 auth.ts에 중앙 집중화합니다(NextAuth() 내보내기: handlers, auth, signIn, signOut). 제공자 비밀을 분산 배치하지 마십시오.
2. middleware.ts(엣지 안전 auth 래퍼)에서 경로를 보호하고, 서버 액션/변경 내에서 세션을 다시 확인하십시오 — 미들웨어는 UX일 뿐, 인가가 아닙니다.
3. 서버 컴포넌트에서는 await auth()를 통해 세션을 읽습니다. 클라이언트 컴포넌트에서는 <SessionProvider>와 함께 next-auth/react의 useSession()을 사용합니다.
4. 비밀(AUTH_SECRET, 제공자 키)을 NEXT_PUBLIC_ 접두사로 절대 노출하지 마십시오. 부트 시 zod로 환경 변수를 검증하십시오.
5. 역할 확인: 모듈 증강(user.role)을 통해 세션 타입을 확장하고 서버에서 강제 적용합니다.

패턴

// auth.ts
import NextAuth from 'next-auth';
import GitHub from 'next-auth/providers/github';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async session({ session, token }) {
      if (session.user) (session.user as { role?: string }).role = token.role as string;
      return session;
    },
    async jwt({ token, user }) {
      if (user) token.role = (user as { role?: string }).role ?? 'user';
      return token;
    },
  },
});

// middleware.ts
export { auth as middleware } from '@/auth';
export const config = { matcher: ['/dashboard/:path*', '/admin/:path*'] };

// app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth';
export const { GET, POST } = handlers;

// 서버 컴포넌트 게이트
import { auth } from '@/auth';
import { redirect } from 'next/navigation';

export default async function AdminPage() {
  const session = await auth();
  if (!session?.user) redirect('/login');
  if ((session.user as { role?: string }).role !== 'admin')
    redirect('/dashboard');
  return <AdminView />;
}

// types/next-auth.d.ts — 역할 증강
import 'next-auth';
declare module 'next-auth' {
  interface User { role?: string }
}

체크리스트

• middleware.ts 매처가 보호 경로를 포함합니까?
• 세션이 액션/변경에서 다시 확인되었습니까?
• 클라이언트에 노출된 비밀이 없습니까?
• 역할이 UI 숨김만이 아닌 서버 측에서 강제 적용되었습니까?
• 로그아웃 및 세션 만료가 처리되었습니까?