# 통합 인증 시스템 아키텍처

## 개요
로빙 서비스의 통합 인증 시스템으로 Gmail, Slack 등 다양한 OAuth 제공자를 지원합니다.

## 시스템 구성

### 1. Auth Server (포트 9000)
- **위치**: `/home/admin/auth-server`
- **기술 스택**: FastAPI, PostgreSQL, Redis
- **주요 기능**:
  - OAuth 2.0/OIDC 인증
  - JWT 토큰 발급 및 검증
  - 사용자 관리
  - 워크스페이스 권한 관리

### 2. 인증 제공자 (Providers)

#### Gmail OAuth
- **엔드포인트**: `/auth/gmail/login`
- **콜백**: `/auth/gmail/callback`
- **특징**: 
  - 임시 코드 방식 (`/auth/verify`)
  - Redis에 60초간 토큰 저장
  - JWT 토큰 30일 유효

#### Slack OAuth (OIDC)
- **엔드포인트**: `/auth/slack/login/`
- **콜백**: `/auth/slack/login/callback`
- **특징**:
  - OIDC with form_post
  - GET/POST 콜백 모두 지원
  - 하이브리드 사용자 매핑

#### NAVER WORKS OAuth
- **엔드포인트**: `/auth/naverworks/login`
- **콜백**: `/auth/naverworks/callback`
- **특징**:
  - OAuth 2.0 + OpenID Connect
  - Service Account (JWT) 지원
  - Access Token 1시간, Refresh Token Rotation
  - **결정필요**: Redirect URL 도메인 (auth.ro-being.com vs auth.robeing.com)

### 3. 데이터베이스 구조

#### users 테이블
```sql
- id: UUID (Primary Key)
- email: VARCHAR(255) UNIQUE
- username: VARCHAR(100) UNIQUE  
- name: VARCHAR(255)
- created_at: TIMESTAMP
```

#### slack_user_mapping 테이블
```sql
- slack_user_id: VARCHAR(100)
- slack_workspace_id: UUID
- user_id: UUID (FK → users.id)
- created_at: TIMESTAMP
- PRIMARY KEY (slack_user_id, slack_workspace_id)
```

#### gmail_token 테이블
```sql
- id: UUID
- user_id: UUID (FK → users.id)
- access_token: TEXT (암호화 필요)
- refresh_token: TEXT
- expires_at: TIMESTAMP
```

### 4. 인증 플로우

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as Auth Server
    participant O as OAuth Provider
    participant R as Redis
    participant D as Database

    U->>F: 로그인 클릭
    F->>A: GET /auth/{provider}/login
    A->>R: state 저장 (CSRF 방지)
    A->>O: Redirect to OAuth
    O->>U: 권한 요청
    U->>O: 승인
    O->>A: POST/GET callback with code
    A->>O: Exchange code for token
    O->>A: Return user info
    A->>D: 사용자 조회/생성
    A->>R: 임시 코드 저장
    A->>F: Redirect with temp code
    F->>A: POST /auth/verify
    A->>R: 코드 검증
    A->>F: Return JWT token
    F->>F: localStorage 저장
```

## 현재 구현 상태

### 완료된 기능 ✅
- Gmail OAuth 로그인
- Slack OIDC 로그인
- JWT 토큰 발급 (30일)
- Redis 기반 state 관리
- 사용자 자동 생성/연동

### 임시 해결책 ⚠️
1. **Frontend-Backend 불일치**
   - Frontend가 `/auth/verify` 방식 사용
   - Slack도 임시 코드 방식으로 맞춤
   
2. **DB 스키마 불일치**
   - company vs workspaces 테이블 공존
   - relationship 주석 처리

3. **하드코딩된 값**
   - redirect_uri: "http://localhost:3000"
   - callback_url: "https://auth.ro-being.com/..."

## Gmail Passport 시스템

### 엔드포인트
1. **발급 시작**: `GET /auth/gmail/passport`
   - Parameters:
     - `user_id`: 사용자 ID (필수)
     - `return_url`: OAuth 완료 후 돌아갈 URL (선택)
   - Response: Google OAuth 페이지로 302 Redirect

2. **콜백 처리**: `GET /auth/gmail/passport/callback`
   - Google OAuth 콜백 자동 처리
   - 토큰 저장 후 return_url 또는 /game으로 리다이렉트
   - 성공 시: `?gmail=success&email={email}` 파라미터 추가

### 특징
- **원페이지 복귀**: OAuth 인증 후 원래 있던 페이지로 자동 복귀
- **상태 관리**: state 파라미터에 return_url 포함하여 전달
- **토큰 저장**: gmail_token 테이블에 암호화 저장

## 보안 고려사항

### 구현된 보안 기능
- CSRF 방지 (state 파라미터)
- 1회용 임시 코드 (60초 TTL)
- HTTPS only cookies
- JWT 서명 검증


## 환경 변수

### 필수 설정
```env
# JWT
JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256
JWT_EXPIRATION_DAYS=30

# Slack OAuth
SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
SLACK_REDIRECT_URI=

# Gmail OAuth
GMAIL_CLIENT_ID=
GMAIL_CLIENT_SECRET=
GMAIL_REDIRECT_URI=

# NAVER WORKS OAuth
NAVERWORKS_CLIENT_ID=
NAVERWORKS_CLIENT_SECRET=
NAVERWORKS_REDIRECT_URI=
NAVERWORKS_SERVICE_ACCOUNT=
NAVERWORKS_PRIVATE_KEY_PATH=

# Redis
REDIS_URL=redis://localhost:6379/0

# PostgreSQL
DATABASE_URL=postgresql://robeings:password@localhost/main_db
```

## 향후 개선 계획

### 단기 (1-2주)
1. DB 스키마 통일 (company → workspaces)
2. Frontend 인증 방식 통일
3. 환경변수 정리

### 중기 (1개월)
1. Refresh Token 구현
2. 다중 OAuth 제공자 통합 관리
3. 권한 시스템 고도화

### 장기 (3개월)
1. SSO (Single Sign-On) 구현
2. 2FA (Two-Factor Authentication)
3. 감사 로그 시스템

## 관련 문서
- [Slack OAuth 구현 상세](/home/heejae/DOCS/troubleshooting/250831_slack_oauth_login_implementation.md)
- [UUID 변환 시스템](./uuid_conversion_system.md)
- [Gateway Proxy Patterns](./gateway_proxy_patterns.md)