195 lines
4.8 KiB
Markdown
195 lines
4.8 KiB
Markdown
# 통합 인증 시스템 아키텍처
|
|
|
|
## 개요
|
|
로빙 서비스의 통합 인증 시스템으로 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 콜백 모두 지원
|
|
- 하이브리드 사용자 매핑
|
|
|
|
### 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_tokens 테이블
|
|
```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 스키마 불일치**
|
|
- companies 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_tokens 테이블에 암호화 저장
|
|
|
|
## 보안 고려사항
|
|
|
|
### 구현된 보안 기능
|
|
- CSRF 방지 (state 파라미터)
|
|
- 1회용 임시 코드 (60초 TTL)
|
|
- HTTPS only cookies
|
|
- JWT 서명 검증
|
|
|
|
### 추가 필요 사항
|
|
- PKCE (Proof Key for Code Exchange)
|
|
- Refresh Token 구현
|
|
- Rate Limiting 및 본인 확인(user_id=JWT.sub 매칭)
|
|
- 토큰 암호화 저장
|
|
|
|
## 환경 변수
|
|
|
|
### 필수 설정
|
|
```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=
|
|
|
|
# Redis
|
|
REDIS_URL=redis://localhost:6379/0
|
|
|
|
# PostgreSQL
|
|
DATABASE_URL=postgresql://robeings:password@localhost/main_db
|
|
```
|
|
|
|
## 향후 개선 계획
|
|
|
|
### 단기 (1-2주)
|
|
1. DB 스키마 통일 (companies → 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)
|