OAuth 2.0 인증 시스템 프로젝트

aimond.io 에서 서비스할 대상 시스템의 프로토타입을 구성합니다.

📋 목차

• 프로젝트 개요
• 시스템 아키텍처
• 기술 스택
• 서비스 구성
• 빠른 시작
• 개발 가이드
• API 문서
• 배포 가이드
• 문서

🎯 프로젝트 개요

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

주요 특징

• ✅ OAuth 2.0 표준 준수: 완벽한 OAuth 2.0 플로우 구현
• ✅ 동적 테마 시스템: 애플리케이션별 맞춤형 인증 페이지
• ✅ 3단계 권한 체계: System Admin, Group Admin, User
• ✅ API Gateway: Apache APISIX를 통한 트래픽 관리
• ✅ 마이크로서비스 아키텍처: 확장 가능한 서비스 구조
• ✅ 컨테이너 기반: Docker를 통한 일관된 개발/운영 환경

🏗️ 시스템 아키텍처

graph TB
    subgraph "Client Layer"
        Browser[사용자 브라우저]
        Mobile[모바일 앱]
        API[API 클라이언트]
    end
    
    subgraph "API Gateway Layer"
        APISIX[Apache APISIX<br/>Rate Limiting<br/>Authentication<br/>Load Balancing]
        etcd[etcd<br/>Service Discovery]
    end
    
    subgraph "Application Services"
        OAuth[OAuth Service<br/>FastAPI]
        Frontend[Web Frontend<br/>React + Vite]
    end
    
    subgraph "Data Layer"
        MongoDB[(MongoDB<br/>Users/Apps/History)]
        Redis[(Redis<br/>Cache/Session)]
    end
    
    Browser --> APISIX
    Mobile --> APISIX
    API --> APISIX
    APISIX <--> etcd
    APISIX --> OAuth
    APISIX --> Frontend
    OAuth --> MongoDB
    OAuth --> Redis

🛠️ 기술 스택

API Gateway

• Apache APISIX 3.8.0: 고성능 API Gateway
• etcd 3.5: 서비스 디스커버리 및 설정 관리

Backend

• Python 3.11: 메인 프로그래밍 언어
• FastAPI: 고성능 웹 프레임워크
• Motor: MongoDB 비동기 드라이버
• Authlib: OAuth 2.0 구현
• Celery: 비동기 작업 처리

Frontend

• React 18: UI 라이브러리
• Vite: 빌드 도구
• TypeScript: 타입 안정성
• shadcn/ui: UI 컴포넌트
• Tailwind CSS: 유틸리티 CSS
• Zustand: 상태 관리
• React Query: 서버 상태 관리

Database & Cache

• MongoDB 7.0: 메인 데이터베이스
• Redis 7: 캐싱 및 세션 관리

DevOps

• Docker & Docker Compose: 컨테이너화
• Kubernetes: 프로덕션 오케스트레이션
• Nexus: 아티팩트 저장소

📦 서비스 구성

1. OAuth 인증 서비스 (/oauth)

백엔드 (/oauth/backend)

FastAPI 기반 OAuth 2.0 인증 서버

주요 기능:

• OAuth 2.0 Authorization Code Flow
• JWT 토큰 발급 및 검증
• 사용자 인증 및 권한 관리
• 애플리케이션 등록 및 관리
• 인증 히스토리 추적

디렉토리 구조:

oauth/backend/
├── app/
│   ├── api/           # API 엔드포인트
│   ├── core/          # 핵심 설정 및 유틸리티
│   ├── models/        # 데이터 모델
│   ├── services/      # 비즈니스 로직
│   └── main.py        # 애플리케이션 진입점
├── tests/             # 테스트 코드
├── requirements.txt   # Python 의존성
└── Dockerfile        # 컨테이너 이미지

프론트엔드 (/oauth/frontend)

React + TypeScript 기반 인증 UI

주요 기능:

• 동적 테마 적용 로그인 페이지
• 사용자 프로필 관리
• 애플리케이션 관리 대시보드
• 권한 설정 인터페이스
• 인증 히스토리 뷰어

디렉토리 구조:

oauth/frontend/
├── src/
│   ├── components/    # React 컴포넌트
│   ├── pages/        # 페이지 컴포넌트
│   ├── hooks/        # Custom Hooks
│   ├── services/     # API 서비스
│   ├── stores/       # 상태 관리
│   └── utils/        # 유틸리티 함수
├── public/           # 정적 파일
└── package.json      # Node.js 의존성

2. API Gateway (/apisix)

Apache APISIX 설정 및 라우팅 규칙

주요 설정:

• 라우팅 규칙 (routes.yaml)
• Rate Limiting 정책
• JWT 인증 플러그인
• CORS 설정
• 캐싱 전략

트래픽 제한:

엔드포인트	Rate Limit	Burst
/api/v1/auth/*	10 req/s	20
/api/v1/users/*	100 req/s	50
/api/v1/applications/*	50 req/s	25
/api/v1/admin/*	200 req/s	100

3. 향후 추가될 서비스 (/services)

이 디렉토리에는 OAuth 인증을 사용할 서비스들이 추가됩니다.

🚀 빠른 시작

사전 요구사항

• Docker & Docker Compose
• Git
• Make (선택사항)

1. 저장소 클론

git clone http://gitea.yakenator.io/aimond/works.git
cd works

2. 환경 변수 설정

# 백엔드 환경 변수
cp oauth/backend/.env.example oauth/backend/.env
# .env 파일을 열어 필요한 값 수정

3. Docker Compose로 실행

Makefile 사용 (권장)

# 모든 서비스 시작
make up

# 백그라운드 실행
make up-d

# 로그 확인
make logs

# 서비스 중지
make down

Docker Compose 직접 사용

# 모든 서비스 시작
docker-compose up --build

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

# 로그 확인
docker-compose logs -f

# 서비스 중지
docker-compose down

4. 서비스 접속

• API Gateway: http://localhost:9080
• APISIX Dashboard: http://localhost:9000 (admin/admin123)
• Frontend: http://localhost:5173
• API Documentation: http://localhost:9080/api/v1/docs

💻 개발 가이드

개발 환경 규칙

• 모든 개발은 Docker 컨테이너 환경에서 진행
• 서비스 간 의존성은 healthcheck로 관리
• Hot reload 지원 (백엔드/프론트엔드)

코드 스타일

• Python: Black + Ruff
• TypeScript: ESLint + Prettier
• Commit: Conventional Commits

테스트

# 백엔드 테스트
make test-backend

# 프론트엔드 테스트
make test-frontend

디버깅

# 백엔드 컨테이너 접속
make exec-backend

# MongoDB 쉘 접속
make exec-mongo

# Redis CLI 접속
make exec-redis

📚 API 문서

주요 엔드포인트

인증

• POST /api/v1/auth/login: 로그인
• POST /api/v1/auth/logout: 로그아웃
• POST /api/v1/auth/refresh: 토큰 갱신
• GET /api/v1/auth/authorize: OAuth 인증
• POST /api/v1/auth/token: 토큰 발급

사용자

• GET /api/v1/users/me: 현재 사용자 정보
• PUT /api/v1/users/me: 사용자 정보 수정
• POST /api/v1/users/me/password: 패스워드 변경

애플리케이션

• GET /api/v1/applications: 애플리케이션 목록
• POST /api/v1/applications: 애플리케이션 등록
• PUT /api/v1/applications/{id}: 애플리케이션 수정
• DELETE /api/v1/applications/{id}: 애플리케이션 삭제

상세 API 문서는 oauth/docs/api-specification.md 참조

🚢 배포 가이드

환경별 배포

개발 환경 (dev)

docker-compose up -d

검증 환경 (vei)

cd oauth/configs/vei
docker-compose -f docker-compose.yml up -d

운영 환경 (prod)

kubectl apply -f .k8s/

백업 및 복구

자동 백업

• 매일 새벽 3시 자동 백업
• 1개월 이상 데이터는 압축 아카이빙

수동 백업

# MongoDB 백업
docker-compose exec mongodb mongodump --out /backup

# Redis 백업
docker-compose exec redis redis-cli BGSAVE

📖 문서

핵심 문서

• CLAUDE.md: 프로젝트 규칙 및 가이드
• Architecture: 시스템 아키텍처
• API Specification: API 명세
• APISIX Guide: API Gateway 가이드

개발 문서

• Frontend 개발 가이드 (작성 예정)
• Backend 개발 가이드 (작성 예정)
• 테스트 가이드 (작성 예정)

운영 문서

• 모니터링 가이드 (작성 예정)
• 트러블슈팅 가이드 (작성 예정)
• 성능 튜닝 가이드 (작성 예정)

🔐 보안

보안 기능

• JWT 기반 인증
• Rate Limiting
• IP 제한 (관리자 API)
• CORS 정책
• SQL Injection 방지
• XSS/CSRF 방지

보안 체크리스트

• 환경별 Secret Key 분리
• HTTPS 적용
• WAF 설정
• 정기 보안 감사
• 취약점 스캔

🤝 기여

Git 협업 규칙

• 원격 저장소: http://gitea.yakenator.io/aimond/works.git
• 브랜치 전략:
  • main: 프로덕션
  • develop: 개발
  • feature/*: 기능 개발
• 커밋 규칙: 모든 작업 세션은 git commit으로 마무리

개발 프로세스

1. Feature 브랜치 생성
2. 개발 및 테스트
3. Pull Request 생성
4. 코드 리뷰
5. Merge

📝 라이선스

LICENSE 파일 참조

👥 팀

• 개발: Claude AI Assistant
• 기획/관리: 사용자

🔗 관련 링크

• Gitea Repository
• APISIX Documentation
• FastAPI Documentation
• React Documentation

---

Last Updated: 2024-12-31 Version: 1.0.0