works/CLAUDE.md

OAuth 2.0 인증 시스템

문서 작성 규칙

• 모든 다이어그램은 Mermaid 문법을 사용하여 작성
• 코드 블록은 언어별 하이라이팅 적용
• API 명세는 OpenAPI 3.0 스펙 준수

개발 환경 규칙

• 모든 개발은 Docker 컨테이너 환경에서 진행
• Docker Compose를 통한 통합 개발 환경 구성
• 서비스 간 의존성은 healthcheck를 통해 관리
• 모든 빌드는 depends_on과 condition을 사용하여 순차 실행

Git 협업 규칙

• 원격 저장소: http://gitea.yakenator.io/aimond/works.git
• 모든 작업 세션은 git commit으로 마무리
• 커밋 메시지는 명확하고 구체적으로 작성
• 주요 기능 완료 시 즉시 커밋 및 푸시
• 브랜치 전략: main (production), develop (개발), feature/* (기능별)

프로젝트 개요

엔터프라이즈급 OAuth 2.0 기반 중앙 인증 시스템으로, 멀티 테넌트 환경에서 동적 테마 적용 및 세분화된 권한 관리를 제공합니다.

시스템 아키텍처

기술 스택

• API Gateway: Apache APISIX 3.8.0
• Frontend: React 18 + Vite + TypeScript + Material-UI (MUI)
  • 이전: Lucide React + Tailwind CSS
  • 현재: Material-UI (@mui/material, @emotion/react, @emotion/styled, @mui/icons-material)
  • 디자인: Google OAuth 스타일 UI/UX
• Backend: Python 3.11 + FastAPI + Motor (MongoDB async)
• Database: MongoDB 7.0
• Cache/Queue: Redis 7
• Service Discovery: etcd 3.5
• Container: Docker + Docker Compose
• Orchestration: Kubernetes (Production)
• Repository: Nexus (Artifact Cache)

환경 구성

• dev: 로컬 개발 환경
• vei: 검증계 (Docker 환경)
• prod: 운영계 (K8s 환경)

공통 섹션

프로젝트 구조

/
├── oauth/                    # OAuth 인증 시스템
│   ├── backend/             # FastAPI 백엔드
│   ├── frontend/            # React 프론트엔드
│   ├── docs/                # 상세 문서
│   └── configs/             # 환경별 설정
│       ├── dev/
│       ├── vei/
│       └── prod/
├── services/                # 인증을 사용할 서비스들
├── .docker/                 # Docker 관련 파일
├── .k8s/                    # Kubernetes 매니페스트
└── docker-compose.yml       # 개발 환경 구성

개발 환경 시작하기

사전 요구사항

• Docker & Docker Compose

통합 개발 환경 실행 (Docker Compose)

# 모든 서비스 실행 (개발 모드)
docker-compose up --build

# 백그라운드 실행
docker-compose up -d --build

# 로그 확인
docker-compose logs -f [service_name]

# 서비스 중지
docker-compose down

# 볼륨 포함 삭제
docker-compose down -v

서비스 접속 URL

• API Gateway: http://localhost:9080
• APISIX Dashboard: http://localhost:9000 (admin/admin123)
• Frontend: http://localhost:5173
• Backend API: http://localhost:9080/api/v1 (through APISIX)
• MongoDB: mongodb://localhost:27017
• Redis: redis://localhost:6379

API 엔드포인트

• Health Check: GET http://localhost:9080/health
• API Documentation: http://localhost:9080/api/v1/docs
• APISIX Admin API: http://localhost:9092/apisix/admin
• APISIX Dashboard: http://localhost:9000

OAuth 인증 시스템

[상세 문서는 oauth/docs 참조]

핵심 기능

1. 사용자 관리

• 3단계 권한 체계
  • System Admin: 전체 시스템 관리
  • Group Admin: 그룹/조직 관리
  • User: 일반 사용자

2. 애플리케이션 관리

• 동적 테마 설정
• 애플리케이션별 인증 페이지 커스터마이징
• Client ID/Secret 관리
• Redirect URI 설정

3. 권한 및 데이터 공유

• 공유 가능 권한:
  • 싱글 사인온 (SSO) 여부
  • 이름
  • 성별
  • 생년월일
  • 이메일
  • 전화번호 (선택적)

4. 보안 기능

• JWT 기반 인증
• Refresh Token 관리
• 세션 관리
• 접속 히스토리 추적

5. 데이터 관리

• 접속 히스토리: 1개월 보관 후 압축 아카이빙
• 자동 백업: 매일 새벽 3시 실행
• 데이터 암호화

환경 변수 설정

필수 환경 변수

SECRET_KEY=your-secret-key
MONGODB_URL=mongodb://localhost:27017
DATABASE_NAME=oauth_db
REDIS_URL=redis://localhost:6379
ENVIRONMENT=dev
BACKUP_PATH=/var/backups/oauth
ARCHIVE_PATH=/var/archives/oauth

데이터베이스 스키마

Users Collection

• _id: ObjectId
• email: 이메일 (unique)
• username: 사용자명 (unique)
• full_name: 전체 이름
• role: 권한 (system_admin/group_admin/user)
• hashed_password: 암호화된 비밀번호
• profile_picture: 프로필 사진 URL
• created_at: 생성일시
• updated_at: 수정일시
• last_login: 마지막 로그인

Applications Collection

• _id: ObjectId
• app_name: 애플리케이션 이름
• client_id: OAuth Client ID (unique)
• client_secret: OAuth Client Secret
• redirect_uris: 허용된 Redirect URI 목록
• theme: 테마 설정 (색상, 로고, 폰트 등)
• created_by: 생성자 ID
• created_at: 생성일시

Auth History Collection

• _id: ObjectId
• user_id: 사용자 ID
• application_id: 애플리케이션 ID
• action: 인증 액션 (login/logout/token_refresh)
• ip_address: IP 주소
• user_agent: User Agent
• created_at: 발생일시

백업 및 아카이빙

자동 백업 (Cron Job)

0 3 * * * /usr/local/bin/backup-oauth.sh

백업 스크립트

#!/bin/bash
DATE=$(date +%Y%m%d)
mongodump --uri="mongodb://localhost:27017" --db=oauth_db --out=/var/backups/oauth/$DATE
tar -czf /var/backups/oauth/oauth_backup_$DATE.tar.gz /var/backups/oauth/$DATE
rm -rf /var/backups/oauth/$DATE

배포 가이드

Docker 빌드

# Backend
cd oauth/backend
docker build -t oauth-backend:latest .

# Frontend  
cd oauth/frontend
docker build -t oauth-frontend:latest .

Kubernetes 배포

kubectl apply -f .k8s/oauth-namespace.yaml
kubectl apply -f .k8s/oauth-configmap.yaml
kubectl apply -f .k8s/oauth-secret.yaml
kubectl apply -f .k8s/oauth-deployment.yaml
kubectl apply -f .k8s/oauth-ingress.yaml

모니터링 및 로깅

• Application Logs: /var/log/oauth/
• Access Logs: /var/log/nginx/
• Error Tracking: Sentry 연동 가능
• Metrics: Prometheus + Grafana

성능 최적화

• Redis 캐싱 전략
• MongoDB 인덱싱
• 비동기 처리 (FastAPI + Motor)
• CDN 활용 (정적 자원)

보안 체크리스트

• 환경별 Secret Key 분리
• HTTPS 적용
• Rate Limiting 설정
• CORS 정책 설정
• SQL Injection 방지
• XSS 방지
• CSRF 토큰 구현
• 민감 정보 암호화

트러블슈팅

[상세 내용은 oauth/docs/troubleshooting.md 참조]

추가 문서

• API 명세서
• 보안 가이드
• 성능 튜닝
• 마이그레이션 가이드