DOCS/book/300_architecture/380_authentication_system.md

통합 인증 시스템 아키텍처

개요

로빙 서비스의 통합 인증 시스템으로 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 테이블

- id: UUID (Primary Key)
- email: VARCHAR(255) UNIQUE
- username: VARCHAR(100) UNIQUE  
- name: VARCHAR(255)
- created_at: TIMESTAMP

slack_user_mapping 테이블

- 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 테이블

- id: UUID
- user_id: UUID (FK → users.id)
- access_token: TEXT (암호화 필요)
- refresh_token: TEXT
- expires_at: TIMESTAMP

4. 인증 플로우

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 서명 검증

환경 변수

필수 설정

# 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 구현 상세
• UUID 변환 시스템
• Gateway Proxy Patterns