sam-react-prod/claudedocs/[REF-2025-11-12] session-migration-summary.md

세션 기반 인증 전환 - 프로젝트 요약

📌 프로젝트 개요

목표: JWT 토큰 기반 → 세션 기반 인증으로 전환하여 보안 강화

작업 기간: 2-3일 (백엔드 1-2일, 프론트엔드 1일)

상태: ⏳ 백엔드 준비 중 → 프론트엔드 대기

---

🎯 전환 이유 (보안 강화)

보안 항목	JWT 토큰 (현재)	세션 (전환 후)
로그아웃 효과	쿠키만 삭제, 토큰 유효	세션 파괴, 즉시 차단 ✅
토큰 탈취 시	만료까지 악용 가능 (2시간)	즉시 무효화 가능 ✅
세션 하이재킹 감지	어려움	실시간 감지 (IP/UA) ✅
강제 로그아웃	불가능	관리자가 즉시 가능 ✅
동시 로그인 제한	어려움	1계정 1세션 강제 ✅

결론: ERP 시스템의 민감한 업무 데이터 보호에 세션이 더 적합

---

📊 아키텍처 변경

현재 (JWT 토큰)

[클라이언트] --user_id/pwd--> [Next.js] --user_id/pwd--> [PHP 백엔드]
                                   |                          |
                                   |  <--access_token------   |
                                   |     refresh_token        |
                                   |                          |
[쿠키: access_token] <---저장---   |                          |
[쿠키: refresh_token]              |                          |

전환 후 (세션)

[클라이언트] --user_id/pwd--> [Next.js] --user_id/pwd--> [PHP 백엔드]
                                   |                          |
                                   |  <--세션 생성 ------->  [Redis]
                                   |     Session ID: abc123   |
                                   |                          |
[쿠키: laravel_session=abc123]<-전달-                        |

---

🔄 작업 단계

단계 1: 백엔드 작업 (PHP/Laravel) ⏳ 진행 중

담당: 백엔드 팀 예상 기간: 1-2일

필수 작업

• Redis 세션 드라이버 설정 (.env, config/session.php)
• 인증 가드 변경 (Sanctum → Session)
• 로그인 컨트롤러 수정 (토큰 제거, 세션 생성)
• 로그아웃 컨트롤러 수정 (세션 파괴)
• CORS 설정 (supports_credentials: true)
• 세션 하이재킹 감지 미들웨어 추가
• /api/v1/auth/check 엔드포인트 추가
• /api/v1/refresh 엔드포인트 삭제

권장 작업

• Rate Limiting 적용
• 세션 활동 로그
• 관리자 강제 로그아웃 기능

📄 상세 가이드: SESSION_MIGRATION_BACKEND.md

---

단계 2: 프론트엔드 작업 (Next.js) ⏸️ 대기 중

담당: 프론트엔드 팀 예상 기간: 1일

필수 작업

• src/app/api/auth/login/route.ts 수정

  • credentials: 'include' 추가
  • 백엔드 세션 쿠키 전달
  • 토큰 저장 로직 제거

• src/app/api/auth/logout/route.ts 수정

  • credentials: 'include' 추가
  • 세션 쿠키를 백엔드로 전달

• src/app/api/auth/check/route.ts 수정

  • 백엔드 세션 검증 API 호출
  • 토큰 갱신 로직 제거

• src/middleware.ts 수정

  • laravel_session 쿠키 확인
  • 토큰 쿠키 확인 제거

• 파일 삭제

  • src/app/api/auth/refresh/route.ts
  • src/lib/auth/token-refresh.ts

📄 상세 가이드: SESSION_MIGRATION_FRONTEND.md

---

단계 3: 통합 테스트

담당: 양 팀 협업 예상 기간: 0.5일

• 로그인 플로우 테스트
• 로그아웃 즉시 차단 확인
• 세션 유지 확인 (페이지 새로고침)
• 세션 하이재킹 감지 테스트
• CORS 크로스 도메인 테스트
• 동시 로그인 제한 테스트

---

📋 API 변경 사항 요약

로그인 API

엔드포인트: POST /api/v1/login

요청: 변경 없음

{
  "user_id": "test",
  "user_pwd": "password"
}

응답: 토큰 제거

// ❌ 이전
{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "token_type": "bearer",
  "expires_in": 7200,
  "user": {...}
}

// ✅ 이후
{
  "message": "Login successful",
  "user": {...},
  "tenant": {...},
  "menus": [...],
  "roles": [...]
}
// + Set-Cookie: laravel_session=abc123...

---

로그아웃 API

엔드포인트: POST /api/v1/logout

변경 사항:

• 세션 쿠키를 받아 Redis에서 세션 삭제
• 즉시 접근 차단

---

인증 체크 API (신규)

엔드포인트: GET /api/v1/auth/check

응답:

{
  "authenticated": true,
  "user": {
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com"
  }
}

---

토큰 갱신 API (삭제)

엔드포인트: POST /api/v1/refresh ❌ 삭제

이유: 세션은 활동 시 자동 연장됨

---

🔐 보안 기능

1. 세션 하이재킹 자동 감지

// 백엔드 미들웨어가 자동 감지
if (session('ip_address') !== request()->ip()) {
    // 세션 즉시 파괴 및 차단
    Auth::logout();
    session()->invalidate();
    return 401 Unauthorized;
}

2. 동시 로그인 제한

// 로그인 시 다른 모든 세션 종료
DB::table('sessions')
    ->where('user_id', $userId)
    ->where('id', '!=', session()->getId())
    ->delete();

3. 관리자 강제 로그아웃

// 관리자가 특정 사용자 세션 강제 종료
DB::table('sessions')
    ->where('user_id', $suspiciousUserId)
    ->delete();

---

🚨 주의사항

백엔드

1. CORS 설정 필수

   'supports_credentials' => true,
   'allowed_origins' => [
       'http://localhost:3000',    // 개발
       'https://yourdomain.com',   // 프로덕션
   ],
   

2. Redis 필수

   • 세션 저장소로 Redis 사용
   • Redis 장애 대비 클러스터 구성 권장

3. HTTPS 필수 (프로덕션)

   SESSION_SECURE_COOKIE=true
   

프론트엔드

1. credentials: 'include' 필수

   fetch(url, {
     credentials: 'include'  // 모든 API 호출에 추가
   });
   

2. 세션 쿠키 이름 확인

   • 백엔드: laravel_session
   • 미들웨어에서 이 이름으로 확인

---

📞 팀 간 커뮤니케이션

백엔드 → 프론트엔드 알림 필요

• 백엔드 배포 완료
• API 응답 형식 변경 완료
• CORS 설정 적용 완료
• 테스트 환경 준비 완료

프론트엔드 → 백엔드 요청 사항

• 프론트엔드 도메인을 CORS allowed_origins에 추가

  • 개발: http://localhost:3000
  • 프로덕션: https://app.yourdomain.com

• 세션 쿠키 이름 확인: laravel_session

---

🧪 테스트 시나리오

시나리오 1: 정상 로그인/로그아웃

1. 로그인 → 세션 쿠키 생성 확인
2. 인증 API 호출 → 정상 작동 확인
3. 로그아웃 → 세션 쿠키 삭제 확인
4. 인증 API 호출 → 401 Unauthorized 확인

시나리오 2: 세션 하이재킹 감지

1. 로그인 (IP: A)
2. 세션 쿠키 복사
3. 다른 IP(B)에서 같은 쿠키 사용 시도
4. 자동 차단 확인 (401 Unauthorized)

시나리오 3: 동시 로그인 제한

1. 기기 A에서 로그인
2. 기기 B에서 같은 계정 로그인
3. 기기 A 세션 자동 종료 확인

---

📅 일정

단계	담당	예상 기간	상태
백엔드 작업	백엔드 팀	1-2일	⏳ 진행 중
프론트엔드 작업	프론트엔드 팀	1일	⏸️ 대기
통합 테스트	양 팀	0.5일	⏸️ 대기
스테이징 배포	DevOps	0.5일	⏸️ 대기
프로덕션 배포	DevOps	협의	⏸️ 대기

---

📚 문서 목록

1. SESSION_MIGRATION_BACKEND.md - 백엔드 상세 가이드
2. SESSION_MIGRATION_FRONTEND.md - 프론트엔드 상세 가이드
3. SESSION_MIGRATION_SUMMARY.md - 본 문서 (프로젝트 요약)

---

🎯 완료 기준

백엔드 완료 조건

• 세션 기반 인증 구현 완료
• 세션 하이재킹 감지 작동
• CORS 설정 완료
• API 응답 형식 변경 완료
• 단위 테스트 통과

프론트엔드 완료 조건

• 토큰 관련 코드 제거 완료
• 세션 쿠키 기반 인증 적용
• 모든 API 호출에 credentials: 'include' 추가
• 로그인/로그아웃 플로우 정상 작동

통합 테스트 완료 조건

• 로그인/로그아웃 시나리오 통과
• 세션 하이재킹 감지 작동 확인
• 동시 로그인 제한 작동 확인
• CORS 에러 없음

---

작성일: 2025-11-12 작성자: Claude Code 버전: 1.0 상태: ⏳ 백엔드 작업 진행 중