sam-react-prod/docs/[REF] 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`

**요청**: 변경 없음
```json
{
  "user_id": "test",
  "user_pwd": "password"
}
```

**응답**: 토큰 제거
```json
// ❌ 이전
{
  "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`

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

---

### 토큰 갱신 API (삭제)

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

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

---

## 🔐 보안 기능

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

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

### 2. 동시 로그인 제한

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

### 3. 관리자 강제 로그아웃

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

---

## 🚨 주의사항

### 백엔드

1. **CORS 설정 필수**
   ```php
   'supports_credentials' => true,
   'allowed_origins' => [
       'http://localhost:3000',    // 개발
       'https://yourdomain.com',   // 프로덕션
   ],
   ```

2. **Redis 필수**
   - 세션 저장소로 Redis 사용
   - Redis 장애 대비 클러스터 구성 권장

3. **HTTPS 필수 (프로덕션)**
   ```bash
   SESSION_SECURE_COOKIE=true
   ```

### 프론트엔드

1. **credentials: 'include' 필수**
   ```typescript
   fetch(url, {
     credentials: 'include'  // 모든 API 호출에 추가
   });
   ```

2. **세션 쿠키 이름 확인**
   - 백엔드: `laravel_session`
   - 미들웨어에서 이 이름으로 확인

---

## 📞 팀 간 커뮤니케이션

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

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

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

- [ ] 프론트엔드 도메인을 CORS `allowed_origins`에 추가
  - 개발: `http://localhost:3000`
  - 프로덕션: `https://app.yourdomain.com`

- [ ] 세션 쿠키 이름 확인: `laravel_session`

---

## 🧪 테스트 시나리오

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

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

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

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

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

```bash
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
**상태**: ⏳ 백엔드 작업 진행 중