[TECH-QA] NextAuth.js

Posted 14 days Updated 14 days

By 베짱이가 되고싶은 개미。

기본 설정

환경 변수 설정

AUTH_SECRET

프로젝트 루트에 .env 파일을 생성하고 필요한 환경 변수를 추가합니다.

AUTH_SECRET=your-secret-key
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret

AUTH_SECRET은 JWT 암호화를 위해 필수입니다. ext-auth에서 AUTH_SECRET은 세션 관리와 JWT(JSON Web Token) 서명을 위해 사용되는 비밀 키(secret key)입니다. 이 환경 변수는 NextAuth.js가 사용자 세션을 안전하게 암호화하고 인증 토큰을 생성하거나 검증할 때 사용됩니다. openssl rand -base64 32 명령어로 생성할 수 있습니다.

AUTH_SECRET은 유저별로 생성되거나 전달되지 않습니다.
AUTH_SECRET은 애플리케이션 수준에서 설정되는 단일 비밀 키로, 모든 사용자에 대해 동일하게 사용됩니다. 즉, 개별 유저마다 다른 AUTH_SECRET을 사용할 필요는 없습니다. 이 키는 NextAuth.js가 세션 관리와 JWT 서명을 위해 서버 측에서 사용하는 고정된 값입니다. 이 모든 작업은 서버에서 일관되게 이루어지며, 유저별로 다른 키를 사용할 필요가 없습니다.
JWT 서명: next-auth는 기본적으로 JWT를 사용하여 사용자 세션을 관리합니다. AUTH_SECRET은 JWT를 서명하고 검증하는 데 사용되는 비밀 키로, 이 키가 없거나 잘못되면 토큰이 유효하지 않게 됩니다.
세션 암호화: 세션 데이터(예: 사용자 정보)를 암호화하여 보안을 강화합니다.
CSRF 토큰 보호: next-auth가 CSRF(Cross-Site Request Forgery) 공격을 방지하기 위해 생성하는 토큰에도 이 키가 사용됩니다.
유저별 토큰과 혼동 가능성: 로그인 시 서버는 유저별로 고유한 JWT를 생성합니다. 이 토큰에는 유저의 정보(예: userId, email, role)가 포함되며, AUTH_SECRET을 사용해 서명됩니다. 하지만 AUTH_SECRET 자체는 토큰을 생성/검증하는 데 사용되는 고정된 키일 뿐입니다.
클라이언트로 전달되지 않음: AUTH_SECRET은 절대 클라이언트(브라우저)로 전달되지 않습니다. 이는 서버 내부에서만 사용되는 비밀 값으로, 유저와 직접적인 상호작용이 없습니다.
세션 데이터: NextAuth.js는 세션 데이터를 데이터베이스(옵션) 또는 JWT 자체에 저장할 수 있습니다. 유저별 정보는 이 세션 데이터에 저장되며, AUTH_SECRET은 이 데이터를 암호화하거나 보호하는 데 사용됩니다.
서버는 요청마다 AUTH_SECRET으로 JWT를 검증해 유저를 인증.

값은 안전하고 예측하기 어려운 문자열이어야 하며, 최소 32자 이상의 무작위 문자열을 사용하는 것이 권장됩니다. 예를 들어, 다음 명령어로 생성할 수 있습니다.

openssl rand -base64 32

App Router를 사용하는 경우, /app/api/auth/[...nextauth]/route.ts 파일에서 설정합니다. 이 파일은 NextAuth가 인증 관련 요청(로그인, 로그아웃, 세션 관리 등)을 처리하는 엔드포인트 역할을 합니다.

만약 Pages Router(/pages)를 사용한다면, /pages/api/auth/[...nextauth].ts 파일에서 비슷한 방식으로 설정하지만, App Router에서는 route.ts 파일을 사용합니다. 또한, App Router에서는 GET, POST 등의 HTTP 메서드를 명시적으로 내보내야 합니다.

App Router: App Router에서는 next-auth의 최신 버전(4.x)을 사용하고, next-auth/middleware를 활용해 보호된 라우트를 설정할 수 있습니다.
미들웨어: 인증이 필요한 페이지를 보호하려면 /app/middleware.ts에서 NextAuth 미들웨어를 설정합니다.
환경 변수: NEXTAUTH_SECRET과 제공자(예: Google, GitHub)의 클라이언트 ID/시크릿은 .env 파일에 설정해야 합니다.

프로젝트 구조 예시

my-nextjs-app/
├── app/
│   ├── api/
│   │   ├── auth/
│   │   │   └── [...nextauth]/
│   │   │       └── route.ts         # NextAuth 설정 (인증 엔드포인트)
│   ├── (auth)/
│   │   ├── login/
│   │   │   └── page.tsx            # 커스텀 로그인 페이지
│   │   ├── signup/
│   │   │   └── page.tsx            # 커스텀 회원가입 페이지 (선택)
│   ├── dashboard/
│   │   └── page.tsx                # 보호된 페이지 (인증 필요)
│   ├── layout.tsx                  # 루트 레이아웃
│   ├── page.tsx                    # 홈 페이지
│   └── globals.css                 # 전역 스타일
├── lib/
│   ├── auth.ts                     # NextAuth 설정 (authOptions)
│   └── db.ts                       # 데이터베이스 연결 (예: Prisma)
├── components/
│   ├── Header.tsx                  # 헤더 컴포넌트
│   ├── Footer.tsx                  # 푸터 컴포넌트
│   └── AuthButton.tsx              # 로그인/로그아웃 버튼 컴포넌트
├── public/
│   ├── images/                     # 정적 이미지 파일
│   └── favicon.ico                 # 파비콘
├── middleware.ts                   # NextAuth 미들웨어 (보호된 라우트 설정)
├── .env                            # 환경 변수 (NEXTAUTH_SECRET, Google ID 등)
├── next.config.mjs                 # Next.js 설정
├── tsconfig.json                   # TypeScript 설정 (TypeScript 사용 시)
├── package.json                    # 프로젝트 의존성 및 스크립트
└── README.md                       # 프로젝트 설명

/app/(auth)/login/page.tsx : 커스텀 로그인 페이지로, signIn 함수를 호출하거나 UI를 제공합니다. 필요에 따라 회원가입 페이지(/signup) 등을 추가.
/app/dashboard/page.tsx : 인증이 필요한 보호된 페이지. NextAuth 미들웨어로 접근을 제어할 수 있음.

📝 app/api/auth/[...nextauth]/route.ts

NextAuth의 인증 엔드포인트를 처리하는 파일입니다. GET, POST 메서드로 NextAuth를 설정합니다.

import NextAuth from "next-auth";
import GitHubProvider from "next-auth/providers/github";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.AUTH_GITHUB_ID,
      clientSecret: process.env.AUTH_GITHUB_SECRET,
    }),
  ],
});

export { handlers as GET, handlers as POST };

NextAuth(authOptions)를 호출하여 Google, GitHub 등의 인증 제공자를 처리하며 handlers는 인증 관련 API 엔드포인트를 처리합니다.

📝 /lib/auth.js

NextAuth 설정(authOptions)을 정의합니다. GoogleProvider, 세션 콜백, JWT 설정 등을 설정합니다.

import NextAuth from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";

export const {
  handlers: { GET, POST },
  auth,
  signIn,
  signOut,
} = NextAuth({
  providers: [
    CredentialsProvider({
      name: "Credentials",
      credentials: {
        username: { label: "Username", type: "text", placeholder: "jsmith" },
        password: { label: "Password", type: "password" },
      },
      async authorize(credentials) {
        const authResponse = await fetch("/your/endpoint", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(credentials),
        });

        if (!authResponse.ok) {
          return null;
        }
        const user = await authResponse.json();
        return user;
      },
    }),
  ],
});

클라이언트 사용법

SessionProvider 사용

클라이언트에서는 next-auth/react의 훅(useSession, signIn, signOut 등)을 사용해 인증 상태를 관리하거나 로그인/로그아웃을 처리합니다.

📝 app/layout.tsx

import { SessionProvider } from "next-auth/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <SessionProvider>{children}</SessionProvider>
      </body>
    </html>
  );
}

App Router에서는 SessionProvider가 클라이언트 컴포넌트이므로, 루트 레이아웃에 직접 추가할 수 없습니다. 별도의 클라이언트 컴포넌트를 만들어야 합니다.

📝 pages/_app.tsx


import { SessionProvider } from "next-auth/react";

export default function App({ Component, pageProps: { session, ...pageProps } }) {
  return (
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  );
}

클라이언트 사용법

useSession 사용

클라이언트에서는 next-auth/react의 훅(useSession, signIn, signOut 등)을 사용해 인증 상태를 관리하거나 로그인/로그아웃을 처리합니다.

클라이언트 컴포넌트에서 useSession 훅을 사용하여 세션 상태를 확인합니다.

// app/client/page.tsx

"use client";

import { useSession, signIn, signOut } from "next-auth/react";

export default function ClientPage() {
  const { data: session, status } = useSession();

  if (status === "loading") return <p>로딩 중...</p>;
  if (status === "authenticated") {
    return (
      <>
        <p>{session.user?.name}님으로 로그인됨</p>
        <button onClick={() => signOut()}>로그아웃</button>
      </>
    );
  }

  return (
    <>
      <p>로그인하지 않음</p>
      <button onClick={() => signIn("github")}>GitHub로 로그인</button>
    </>
  );
}

useSession은 data (세션 객체)와 status (loading, authenticated, unauthenticated)를 반환합니다.
signIn과 signOut은 각각 로그인과 로그아웃을 처리합니다.

세션 업데이트

useSession의 update 메서드를 사용하여 클라이언트 측에서 세션을 업데이트할 수 있습니다.

// app/client/page.tsx
"use client";

import { useSession } from "next-auth/react";

export default function UpdateSessionPage() {
  const { data: session, update } = useSession();

  const handleUpdate = async () => {
    await update({ name: "새로운 이름" }); // 세션 데이터 업데이트
  };

  return (
    <>
      <p>현재 사용자: {session?.user?.name}</p>
      <button onClick={handleUpdate}>이름 업데이트</button>
    </>
  );
}

update 메서드는 서버의 jwt 콜백을 트리거하여 세션 데이터를 갱신합니다.

<서버 측 사용법> App Router에서 서버 세션 확인

📝 app/server/page.tsx

import { auth , GET, POST } from @/app/auth";

export default async function ServerPage() {
  const session = await auth();

  if (!session) {
    return <p>로그인이 필요합니다.</p>;
  }

  return <p>서버에서 확인된 사용자: {session.user?.name}</p>;
}

auth 함수는 서버 컴포넌트, 미들웨어, API 라우트 등에서 사용할 수 있는 통합 메서드입니다.

<서버 측 사용법> Pages Router에서 서버 세션 확인

Pages Router에서는 getServerSession을 사용합니다.

📝 pages/server.js

import { getServerSession } from "next-auth/next";
import { authOptions } from "./api/auth/[...nextauth]";

export default function ServerPage({ session }) {
  if (!session) {
    return <p>로그인이 필요합니다.</p>;
  }

  return <p>서버에서 확인된 사용자: {session.user?.email}</p>;
}

export async function getServerSideProps(context) {
  const session = await getServerSession(context.req, context.res, authOptions);
  return {
    props: {
      session,
    },
  };
}

getServerSession은 세션 확인 속도가 빠르며, 추가 네트워크 요청을 줄입니다.

미들웨어로 페이지 보호

📝 /middleware.ts

NextAuth 미들웨어를 설정하여 특정 경로(예: /dashboard)에 인증이 필요하도록 제한. 예: export { default } from 'next-auth/middleware';

import { withAuth } from "next-auth/middleware";

export default withAuth({
  callbacks: {
    authorized: ({ token }) => !!token, // 토큰이 있으면 인증된 것으로 간주
  },
});

export const config = {
  matcher: ["/dashboard/:path*"], // /dashboard 경로와 하위 경로 보호
};

/dashboard로 시작하는 모든 경로에 대해 인증을 요구

커스텀 로그인 페이지

기본 로그인 페이지를 커스터마이징하려면 pages 옵션을 사용합니다.

📝 app/api/auth/[...nextauth]/route.ts

export const { handlers, auth } = NextAuth({
  providers: [GitHubProvider({ clientId: process.env.AUTH_GITHUB_ID, clientSecret: process.env.AUTH_GITHUB_SECRET })],
  pages: {
    signIn: "/auth/signin",
  },
});

📝 app/auth/signin/page.tsx

import { getProviders, signIn } from "next-auth/react";

export default async function SignIn() {
  const providers = await getProviders();

  return (
    <div>
      <h1>로그인</h1>
      {providers &&
        Object.values(providers).map((provider) => (
          <div key={provider.name}>
            <button onClick={() => signIn(provider.id)}>
              {provider.name}으로 로그인
            </button>
          </div>
        ))}
    </div>
  );
}