Auth.js 설정

웹 애플리케이션의 인증(Authentication)은 사용자가 누구인지 확인하는 과정입니다.

권한 부여(Authorization)는 확인된 사용자가 어떤 기능을 사용할 수 있는지 판단하는 과정입니다.

Next.js에서는 Auth.js를 사용하면 OAuth 로그인, 세션 쿠키, 콜백과 라우트 핸들러를 직접 조립하는 부담을 줄일 수 있습니다.

이 장은 App Router와 Auth.js v5의 Next.js 통합 API를 기준으로 진행합니다. 설치 예제의 beta 배포 태그와 설치된 버전은 프로젝트 잠금 파일로 함께 관리합니다.

핵심은 설정 객체를 여러 파일에서 다시 꺼내 쓰지 않고, 한 번의 NextAuth() 호출에서 handlers, auth, signIn, signOut을 만들어 공유하는 것입니다.

인증 흐름 이해

사용자가 GitHub 로그인을 선택하면 브라우저는 GitHub의 인증 화면으로 이동합니다.

인증이 끝나면 GitHub가 애플리케이션의 콜백 URL로 사용자를 돌려보냅니다.

Auth.js는 콜백 요청을 검증하고 세션 쿠키를 만든 뒤 애플리케이션으로 이동시킵니다.

이후 서버 컴포넌트와 라우트 핸들러는 auth()로 현재 세션을 읽습니다.

클라이언트 컴포넌트는 꼭 필요한 경우에만 useSession()을 사용합니다.

패키지와 환경 변수 설정

먼저 Auth.js 패키지를 설치합니다.

npm install next-auth@beta

Auth.js v5가 안정 버전으로 설치되는 시점에는 프로젝트의 버전 정책에 맞춰 next-auth를 설치하면 됩니다.

프로젝트 루트의 .env.local에 인증 비밀 키와 GitHub OAuth 값을 저장합니다.

AUTH_SECRET=충분히_긴_무작위_문자열
AUTH_GITHUB_ID=GitHub_OAuth_App의_Client_ID
AUTH_GITHUB_SECRET=GitHub_OAuth_App의_Client_Secret

비밀 키는 다음 명령으로 만들 수 있습니다.

npx auth secret

GitHub OAuth App의 개발 환경 콜백 URL은 다음과 같습니다.

http://localhost:3000/api/auth/callback/github

배포 환경에서는 실제 HTTPS 도메인으로 콜백 URL을 별도로 등록합니다.

환경 변수 파일은 저장소에 커밋하지 않습니다.

중앙 인증 모듈 작성

프로젝트의 인증 설정은 src/auth.ts 한곳에 둡니다.

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

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
  session: {
    strategy: 'jwt',
  },
});

GitHub 공급자는 AUTH_GITHUB_ID와 AUTH_GITHUB_SECRET을 자동으로 읽습니다.

App Router 핸들러 연결

Auth.js가 만든 HTTP 핸들러를 catch-all 라우트에 연결합니다.

import { handlers } from '@/auth';

export const { GET, POST } = handlers;

이 파일은 설정을 소유하지 않습니다.

URL 요청을 중앙 인증 모듈의 핸들러로 전달하는 역할만 합니다.

서버에서 세션 읽기

서버 컴포넌트에서는 auth()를 직접 호출합니다.

import { auth } from '@/auth';

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

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

  return <p>{session.user.email} 계정으로 로그인했습니다.</p>;
}

@/auth는 서버 코드에서만 가져옵니다. 브라우저 UI에는 next-auth/react의 클라이언트 API를 사용하며, Provider 비밀 키나 서버 인증 설정을 클라이언트 컴포넌트로 가져오지 않습니다.

로그인 여부만 확인할 때는 session?.user의 존재를 검사합니다.

사용자 식별자나 역할이 필요하다면 이후 콜백에서 세션 타입을 확장합니다.

클라이언트 세션이 필요한 경우

대부분의 페이지는 서버 컴포넌트에서 세션을 읽는 편이 단순합니다.

브라우저에서 세션 변화에 반응해야 하는 작은 UI에만 SessionProvider와 useSession()을 사용합니다.

'use client';

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

export function Providers({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>;
}

import { Providers } from './providers';

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

Provider를 추가하면 루트 전체가 클라이언트 컴포넌트로 바뀌는 것은 아닙니다.

다만 클라이언트 세션이 전혀 필요하지 않다면 Provider도 추가하지 않습니다.

설정 확인

개발 서버를 실행한 뒤 /api/auth/signin에 접속합니다.

GitHub 로그인을 완료하고 애플리케이션으로 돌아오는지 확인합니다.

auth()를 호출한 서버 컴포넌트에서 사용자 정보가 보이는지 확인합니다.

환경 변수를 바꿨다면 개발 서버를 다시 시작합니다.

로그인 실패 시에는 공급자 키, 콜백 URL, AUTH_SECRET 순으로 점검합니다.

설정 파일을 연결하며 확인하기

먼저 src/auth.ts와 src/app/api/auth/[...nextauth]/route.ts를 연결한 뒤, 서버 페이지의 auth() 결과로 로그인 전후를 비교합니다. 이때 브라우저 버튼을 만들기 전에 기본 /api/auth/signin으로도 공급자 인증을 시작할 수 있습니다. 인증 모듈이 준비되었다는 것과 특정 업무 API의 권한 검사가 구현되었다는 것은 별개입니다. Auth.js 설치 안내도 핸들러 연결 뒤 리소스 보호를 별도로 설명합니다.

확인 문제

AccountPage만 사용하는 앱에서 Providers를 제거했습니다. 이것만으로 서버의 auth() 호출이 불가능해지나요? 반대로 ClientAuthButton에 useSession()을 추가할 때 필요한 연결은 무엇인가요? 공급자 설정·핸들러·세션 쿠키는 정상이라고 가정합니다.