NextAuth 기술명세서

Authentication Platform for Vibe Coders 버전 1.0 | NextPlatform | 2026

1. 프로젝트 개요

1.1 프로젝트 정의

NextAuth는 바이브코더가 프로젝트의 성격과 규모에 맞는 인증 시스템을 빠르게 구현할 수 있도록 지원하는 모듈형 인증 플랫폼이다. GitHub 리포지토리 클론 후 원하는 Provider를 선택해 즉시 사용할 수 있는 구조로 설계한다.

1.2 슬로건

Build Authentication in Minutes

1.3 설계 원칙

선택 가능성: 학습용(LocalStorage)부터 엔터프라이즈(OAuth)까지, 프로젝트 단계에 맞는 인증 방식 선택
최소 설정: 환경변수 설정 후 Provider 1개 import로 동작
일관된 인터페이스: 어떤 Provider를 사용하더라도 동일한 API (login, logout, getUser, useAuth) 제공
확장성: 단일 Provider → 멀티 OAuth → AI Agent 인증까지 단계적 확장 가능

2. 지원 Provider 및 적용 시나리오

Provider	난이도	권장 프로젝트	외부 계정 필요
LocalStorage	⭐ 매우 쉬움	강의 실습, 해커톤, 아이디어 검증	없음
Vercel + Neon	⭐⭐ 쉬움	소규모 SaaS, 개인 서비스	Neon 계정
Supabase Auth	⭐⭐ 쉬움	표준 SaaS, 빠른 MVP	Supabase 계정
Google Login	⭐⭐⭐ 중간	B2B, SaaS, AI 서비스	Google Cloud Console
Naver Login	⭐⭐⭐ 중간	국내 사용자 대상 서비스	Naver Developers
Kakao Login	⭐⭐⭐ 중간	B2C, 커뮤니티, 모바일 앱	Kakao Developers

3. 시스템 아키텍처

3.1 전체 구조

[Client - React + Vite]
        ↓
[NextAuth SDK]
  ├── useAuth() Hook
  ├── AuthProvider Component
  └── AuthGuard Component
        ↓
[Authentication Layer]
  ├── LocalAuthProvider
  ├── NeonAuthProvider
  ├── SupabaseAuthProvider
  ├── GoogleAuthProvider
  ├── NaverAuthProvider
  └── KakaoAuthProvider
        ↓
[Storage / External Service]
  ├── Browser LocalStorage
  ├── Neon PostgreSQL (via Vercel Functions)
  ├── Supabase (관리형 Auth + DB)
  └── OAuth 2.0 서버 (Google / Naver / Kakao)

3.2 디렉토리 구조

nextauth/
├── src/
│   ├── providers/
│   │   ├── LocalAuthProvider.ts
│   │   ├── NeonAuthProvider.ts
│   │   ├── SupabaseAuthProvider.ts
│   │   ├── GoogleAuthProvider.ts
│   │   ├── NaverAuthProvider.ts
│   │   └── KakaoAuthProvider.ts
│   ├── core/
│   │   ├── AuthProvider.tsx       # React Context Provider
│   │   ├── AuthGuard.tsx          # 보호 라우트 컴포넌트
│   │   ├── useAuth.ts             # 공통 Hook
│   │   └── types.ts               # 공통 타입 정의
│   ├── rbac/
│   │   ├── roles.ts               # 역할 정의
│   │   └── permissions.ts         # 권한 체크 유틸
│   └── index.ts                   # Public API export
├── api/                           # Vercel / Edge Functions
│   ├── auth/login.ts
│   ├── auth/logout.ts
│   ├── auth/callback.ts           # OAuth Callback 처리
│   └── auth/me.ts
├── examples/
│   ├── localstorage-demo/
│   ├── neon-demo/
│   ├── supabase-demo/
│   └── oauth-demo/
├── .env.example
└── README.md

4. 공통 인터페이스 (Provider 공통 API)

모든 Provider는 아래 인터페이스를 동일하게 구현한다. Provider를 변경해도 컴포넌트 코드는 수정할 필요가 없다.

4.1 User 객체

interface User {
  id: string
  email: string
  name?: string
  avatar?: string
  role: 'guest' | 'user' | 'premium' | 'manager' | 'admin'
  provider: 'local' | 'neon' | 'supabase' | 'google' | 'naver' | 'kakao'
  createdAt: string
}

4.2 AuthProvider Interface

interface IAuthProvider {
  login(credentials: LoginCredentials): Promise<User>
  logout(): Promise<void>
  getUser(): Promise<User | null>
  refreshToken?(): Promise<void>
}

4.3 useAuth Hook

const {
  user,          // User | null
  isLoading,     // boolean
  isAuthenticated, // boolean
  login,         // (credentials) => Promise<void>
  logout,        // () => Promise<void>
  hasRole,       // (role) => boolean
  canAccess,     // (path) => boolean
} = useAuth()

5. Provider별 핵심 구현 명세

5.1 LocalStorage Provider

목적: 코드 학습, 해커톤, 빠른 프로토타이핑

동작 방식:

사용자 계정 정보를 브라우저 LocalStorage에 저장
별도 서버/DB 불필요
페이지 새로고침 후에도 로그인 상태 유지

저장 데이터 구조:

{
  "nextauth_user": {
    "id": "user_001",
    "email": "test@example.com",
    "name": "테스트 유저",
    "role": "user",
    "provider": "local"
  }
}

핵심 구현 포인트:

이메일 + 비밀번호 일치 여부만 체크 (해시 없음, 학습용 목적)
기본 테스트 계정 내장 (admin@test.com / admin, user@test.com / user)
logout() 시 LocalStorage 키 삭제

제약 사항:

실서비스 사용 불가 (보안 취약)
탭 간 세션 동기화 없음

5.2 Vercel + Neon Provider

목적: 소규모 SaaS, 범용 실서비스 표준 구성

기술 스택:

Frontend: React + Vite
API: Vercel Serverless Functions
DB: Neon PostgreSQL
인증 방식: JWT (Access Token) + bcrypt (비밀번호 해시)

DB 스키마:

-- users 테이블
CREATE TABLE users (
  id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email     VARCHAR(255) UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  name      VARCHAR(100),
  role      VARCHAR(50) DEFAULT 'user',
  created_at TIMESTAMP DEFAULT NOW()
);

API 엔드포인트:

메서드	경로	역할
POST	/api/auth/register	회원가입
POST	/api/auth/login	로그인 → JWT 발급
POST	/api/auth/logout	로그아웃 (토큰 무효화)
GET	/api/auth/me	현재 사용자 정보 조회

핵심 구현 포인트:

JWT는 httpOnly Cookie에 저장 (XSS 방어)
비밀번호는 bcrypt(saltRounds: 12)로 해시
Token 만료: Access 1시간 / Refresh 7일

필수 환경변수:

DATABASE_URL=postgresql://...
JWT_SECRET=your_jwt_secret

5.3 Supabase Auth Provider

목적: 2026년 바이브코딩 표준 구성, 빠른 프로덕션 배포

기술 스택:

Supabase Auth (관리형 인증 서비스)
Supabase PostgreSQL (자동 user 테이블 생성)
Supabase SDK (@supabase/supabase-js)

지원 로그인 방식 (이 Provider 하나로 모두 처리):

이메일 + 비밀번호
Magic Link (이메일 링크 로그인)
OTP (6자리 인증 코드)
Google / GitHub OAuth (Supabase 대시보드에서 활성화)

핵심 구현 포인트:

Supabase SDK의 supabase.auth.signInWithPassword(), signInWithOtp() 등 직접 활용
onAuthStateChange 리스너로 로그인 상태 실시간 동기화
Row Level Security(RLS)로 데이터 접근 제어 내장

필수 환경변수:

VITE_SUPABASE_URL=https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key

5.4 Google Login Provider

목적: B2B SaaS, AI 서비스, 글로벌 사용자 대상 서비스

인증 흐름 (OAuth 2.0 + PKCE):

1. 사용자 "Google로 로그인" 클릭
2. Google OAuth 동의 화면으로 리다이렉트
3. 사용자 동의 → Google이 Authorization Code 반환
4. /api/auth/callback 에서 Code → Access Token 교환
5. Access Token으로 Google 사용자 정보 조회
6. 내부 User 객체 생성 후 JWT 발급
7. 클라이언트에 세션 전달

핵심 구현 포인트:

Callback URL: {BASE_URL}/api/auth/callback/google
사용자 정보 매핑: Google sub → 내부 id, email, name, picture → avatar
신규 사용자: 자동 회원가입 (role: ‘user’)
기존 사용자: 로그인 처리

필수 환경변수:

GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret
NEXTAUTH_URL=https://your-domain.com

5.5 Naver Login Provider

목적: 국내 사용자 중심 서비스, 40~60대 주요 사용자층 대상

인증 흐름:

Naver OAuth 2.0 표준 흐름 적용
Callback URL: {BASE_URL}/api/auth/callback/naver
상태값(state) CSRF 방어 필수

제공 사용자 정보:

이름, 이메일, 프로필 이미지, 성별, 생년월일 (사용자 동의 항목)

핵심 구현 포인트:

Naver 개발자 센터에서 서비스 URL 및 Callback URL 사전 등록 필요
이메일이 없는 경우(null) 처리 로직 필요

필수 환경변수:

NAVER_CLIENT_ID=your_client_id
NAVER_CLIENT_SECRET=your_client_secret
NEXTAUTH_URL=https://your-domain.com

5.6 Kakao Login Provider

목적: B2C 서비스, 커뮤니티, 모바일 중심 앱

인증 흐름:

Kakao REST API를 통한 OAuth 2.0
Callback URL: {BASE_URL}/api/auth/callback/kakao
카카오 비즈니스 채널 연결 시 추가 정보 획득 가능

제공 사용자 정보:

닉네임, 프로필 이미지, 이메일 (동의 항목), 카카오 고유 ID

핵심 구현 포인트:

카카오 이메일은 선택 동의 항목 → null 처리 필수
카카오 고유 ID(id)를 provider_id로 저장, 이메일 없어도 계정 식별 가능

필수 환경변수:

KAKAO_REST_API_KEY=your_rest_api_key
KAKAO_CLIENT_SECRET=your_client_secret
NEXTAUTH_URL=https://your-domain.com

6. 계정 연결 (Multi-Provider 지원)

하나의 사용자가 여러 OAuth 방식으로 로그인할 수 있도록 계정 연결 기능을 제공한다.

6.1 DB 스키마 확장

-- OAuth 계정 연결 테이블
CREATE TABLE user_accounts (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID REFERENCES users(id) ON DELETE CASCADE,
  provider    VARCHAR(50) NOT NULL,   -- 'google', 'naver', 'kakao'
  provider_id VARCHAR(255) NOT NULL,  -- OAuth 공급자 고유 ID
  created_at  TIMESTAMP DEFAULT NOW(),
  UNIQUE(provider, provider_id)
);

6.2 계정 연결 흐름

1. Google 로그인 → 신규: users + user_accounts 생성
2. 동일 이메일로 Kakao 로그인 시도
3. 이메일 기준 기존 계정 탐지
4. user_accounts에 Kakao provider 추가 (계정 병합)
5. 이후 Google / Kakao 모두로 동일 계정 로그인 가능

7. RBAC (역할 기반 접근 제어)

7.1 기본 역할 체계

역할	설명	기본 접근 범위
`guest`	비로그인 상태	공개 페이지만
`user`	일반 가입자	기본 기능
`premium`	유료 구독자	기본 + 프리미엄 기능
`manager`	팀 관리자	premium + 팀 관리
`admin`	시스템 관리자	전체

7.2 라우트 보호

// AuthGuard 사용 예시
<AuthGuard requiredRole="premium">
  <PremiumContent />
</AuthGuard>

// Hook 사용 예시
const { hasRole, canAccess } = useAuth()
if (hasRole('admin')) { /* 관리자 전용 UI */ }
if (canAccess('/dashboard')) { /* 접근 가능 여부 */ }

8. 관리자 대시보드 (Auth Dashboard)

8.1 주요 기능

기능	설명
사용자 목록 조회	가입일, Provider, 역할 필터링
역할 변경	user → premium / manager 등 즉시 변경
계정 비활성화	탈퇴 처리 / 접근 차단
가입 통계	일별 가입자 수, Provider별 분포
로그인 로그	최근 로그인 이력 (IP, 시간, Provider)

8.2 접근 제한

role === 'admin' 인 사용자만 접근 가능
AuthGuard로 라우트 보호 필수

9. 개발 로드맵 (MVP 우선순위)

Phase 1 — 핵심 (LocalStorage + Neon)

LocalStorage Provider 구현
Vercel + Neon JWT 인증 구현
useAuth Hook, AuthProvider, AuthGuard 컴포넌트
기본 RBAC (user / admin)
README + 예시 앱 2개

Phase 2 — 표준 (Supabase + RBAC 확장)

Supabase Auth Provider 구현
RBAC 5단계 전체 구현
관리자 대시보드 기본 기능
.env.example 및 설정 가이드

Phase 3 — OAuth (Google + Naver + Kakao)

Google Login Provider 구현
Naver Login Provider 구현
Kakao Login Provider 구현
OAuth Callback API 공통화

Phase 4 — 확장 (멀티 OAuth + Agent 인증)

Multi-Provider 계정 연결
Organization / Team 관리
AI Agent 인증 확장 (MCP Auth, API Key Vault)

10. 환경별 권장 Provider 조합

프로젝트 단계	권장 구성	이유
강의 실습 / 해커톤	LocalStorage	설정 0, 즉시 시작
개인 프로젝트 MVP	Vercel + Neon	저렴하고 실서비스 가능
SaaS 표준 구성	Supabase Auth	OAuth 포함, 확장성 우수
국내 B2C 서비스	Supabase + Kakao	가입 전환율 최적
B2B / AI 서비스	Supabase + Google	글로벌 표준, OIDC 지원

11. GitHub 리포지토리 사용 방법

# 1. 클론
git clone https://github.com/junsang-dong/nextauth.git

# 2. 패키지 설치
npm install

# 3. 환경변수 설정
cp .env.example .env.local
# .env.local에 사용할 Provider의 키 입력

# 4. 개발 서버 실행
npm run dev

Provider 선택은 src/config/auth.config.ts에서 한 줄로 변경한다.

export const authConfig = {
  provider: 'supabase',  // 'local' | 'neon' | 'supabase' | 'google' | 'naver' | 'kakao'
}

NextAuth Technical Specification v1.0 NextPlatform | nextplatform.net | naebon@naver.com

Share on Facebook

Post on X

Save

NextAuth 모듈형 인증 플랫폼 활용 가이드