소셜 로그인(NextAuth.js) 완벽 가이드
복잡한 백엔드 로직 없이, 클릭 몇 번으로 Google과 Kakao 로그인을 연동하는 방법을 배워봅니다.
초보자를 위한 UI 가이드를 기본으로, 2025년 기준 NextAuth v5(Auth.js) 패턴과 Netlify 배포 팁을 보충했습니다.
1. 필수 패키지 설치
Next.js 환경에서 인증을 도와주는 next-auth 라이브러리를 설치합니다.
npm install next-auth2. NextAuth v5 설정 (App Router)
Next.js App Router에서는 app/api/auth/[...nextauth]/route.ts 파일 하나로 모든 인증 요청을 처리합니다.
import NextAuth from "next-auth"
import Google from "next-auth/providers/google"
const handler = NextAuth({
providers: [
Google({
clientId: process.env.GOOGLE_OAUTH_ID!,
clientSecret: process.env.GOOGLE_OAUTH_SECRET!,
})
],
// 보안을 위한 필수 비밀 키
secret: process.env.NEXTAUTH_SECRET,
})
export { handler as GET, handler as POST }💡 Tip: process.env.GOOGLE_OAUTH_ID! 뒤의 느낌표(!)는 TypeScript에게 "이 값은 반드시 존재해!"라고 알려주는 표시입니다.
3. Google 클라이언트 ID 발급받기
구글 로그인을 사용하려면 구글로부터 "우리 앱이 로그인을 사용해도 된다"는 허락을 받아야 합니다.
OAuth 동의 화면 설정
API 및 서비스 > OAuth 동의 화면으로 이동합니다.

외부 사용자를 위한 'External'을 선택하고 앱 이름, 개발자 이메일 등 필수 항목을 입력합니다.

사용자 인증 정보 생성
사용자 인증 정보 > 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭합니다.
애플리케이션 유형은 '웹 애플리케이션'을 선택하세요.


생성이 완료되면 아래와 같이 클라이언트 ID와 보안 비밀번호가 표시됩니다.

승인된 리디렉션 URI 확인 (중요!)
방금 만든 클라이언트의 상세 화면에서 “승인된 리디렉션 URI”에 실제 콜백 URL이 정확히 입력되어 있는지 확인해야 합니다.
로컬 개발용:http://localhost:3000/api/auth/callback/google
배포용(보충):https://your-site.netlify.app/api/auth/callback/google
💡 주소가 불일치하면 redirect_mismatch 에러가 발생하므로 주의하세요.
4. Netlify 환경 변수 설정 (매우 중요)
배포 환경에서는 .env.local 파일이 작동하지 않습니다. 반드시 Netlify 대시보드에서 직접 변수를 등록해야 합니다.
Netlify > Site settings > Environment variables에 다음 4가질 추가하세요:
GOOGLE_OAUTH_ID: 발급받은 클라이언트 IDGOOGLE_OAUTH_SECRET: 발급받은 클라이언트 비밀번호NEXTAUTH_SECRET: 랜덤한 긴 문자열 (터미널에서openssl rand -base64 32로 생성 추천)NEXTAUTH_URL:https://your-site.netlify.app(실제 배포 도메인)
🚩 주의: NEXTAUTH_URL이 없으면 배포 서버에서 로그인 후 콜백 시 에러가 발생합니다.
5. 세션 컨텍스트 및 UI 구현
로그인 상태를 앱 어디에서나 확인할 수 있도록 SessionProvider로 앱을 감싸주고, useSession 훅으로 로그인 기능을 완성합니다.
'use client';
import { SessionProvider } from 'next-auth/react';
export default function AuthContext({ children }) {
return <SessionProvider>{children}</SessionProvider>;
}import { useSession, signIn, signOut } from 'next-auth/react';
export default function Header() {
const { data: session } = useSession();
return (
<header>
{session ? (
<button onClick={() => signOut()}>로그아웃</button>
) : (
<button onClick={() => signIn('google')}>구글로 로그인</button>
)}
</header>
);
}6. 배포 후 체크리스트 (보충)
캐시 삭제: Netlify 메뉴에서 "Clear cache and deploy site"를 클릭해 보세요.
결과 확인: /api/auth/session에 접속하여 사용자 데이터 JSON이 출력되는지 확인합니다.
에러 대응: Netlify Deploys > Functions 로그에서 상세 오류 원인 파악
7. 로그인 UI 커스텀하기 (심화)
기본 제공 UI 대신 나만의 멋진 로그인 페이지를 만들고 싶다면 pages 설정을 추가하세요.
const handler = NextAuth({
pages: {
signIn: '/auth/login', // 커스텀 로그인 페이지 경로
},
// ... providers 설정
});이제 app/auth/login/page.tsx 파일을 만들어 원하는 대로 디자인하면 됩니다!
8. JWT 세션 vs 데이터 저장 (DB 설계)
NextAuth는 기본적으로 JWT(JSON Web Token) 방식을 사용합니다. 따라서 별도의 DB를 연결하지 않아도 로그인 상태 유지와 사용자 이름/이메일 확인 등의 세션 기능은 정상적으로 작동합니다.
💡 핵심 요약
- JWT 세션: DB 없이도 "로그인 여부"와 "기본 프로필"을 사용할 수 있는 경제적인 방식입니다.
- 데이터 저장: 하지만 사용자가 작성한 글, 결제 내역 등을 영구 저장하려면 반드시 Prisma 같은 DB를 따로 설계하고 연결해야 합니다.
실습 영상 (무작정 따라하기)
아래 영상을 통해 NextAuth.js를 이용한 구글 소셜 로그인 연동 과정을 실습해 보세요.
▲ 구글 소셜 로그인 연동 실습 가이드
💡 참고: 영상의 후반부는 실제 구현 중 발생하는 버그를 수정하는 과정이 포함되어 있습니다. 실무에서 겪을 수 있는 트러블슈팅 과정을 함께 확인해 보세요.

