ivada-infra/DOCS

Fork 0

happybell80 d8ca127454 docs: Admin Dashboard 및 Gateway 문제 해결 문서 추가

2025-11-17 19:42:15 +09:00

9.1 KiB

Raw Blame History

Admin Dashboard JWT 검증 분리 구현

날짜: 2025-11-17
작업자: Claude (51123 서버 관리자)
관련 서버: 51123
관련 서비스: robeing-gateway, frontend-base, nginx

배경

관리자 대시보드(/admin) 접근 시 JWT 검증 문제 발생:

문제 상황

브라우저가 /admin HTML 페이지를 요청
Gateway가 모든 요청에 JWT 검증 요구 → 401 반환
HTML 페이지 자체를 받지 못해서 JavaScript 실행 불가
JavaScript가 localStorage에서 JWT를 가져와서 API 요청에 포함해야 하는데, HTML이 로드되지 않아 실행 불가

근본 원인

Gateway의 /admin/{path:path} 라우트가 모든 요청에 JWT 검증을 요구하고 있었음:

HTML 페이지 요청도 JWT 검증 필요 → 잘못된 설계
HTML은 공개적으로 접근 가능해야 하고, JavaScript가 로드된 후 JWT 확인 필요

해결 방안

올바른 설계

/admin (HTML) → JWT 검증 제외 → frontend-base
/admin/api/* (데이터 API) → JWT 검증 필요 → Gateway → robeing-monitor

구현 전략

HTML/정적 파일: JWT 검증 없이 프록시 (JavaScript에서 JWT 체크)
API 요청: JWT 검증 필요 (보안 유지)

구현 내역

1. Gateway 라우팅 수정

파일: /home/admin/robeing-gateway/app/main.py

변경 사항:

/admin/{path:path} 라우트에서 조건부 JWT 검증 적용
path.startswith("api/")로 API 요청 구분
HTML/정적 파일은 JWT 검증 없이 프록시
API 요청만 JWT 검증 수행

@app.api_route("/admin/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def admin_proxy(
    path: str,
    request: Request,
    authorization: Optional[str] = Header(None)
):
    """
    Admin dashboard - proxy to frontend-base (51123:8000)
    
    - HTML/정적 파일: JWT 검증 없이 프록시 (JavaScript에서 JWT 체크)
    - API 요청 (/admin/api/*): JWT 검증 필요
    """
    frontend_base_url = "http://localhost:8000"
    target_url = f"{frontend_base_url}/admin/{path}" if path else f"{frontend_base_url}/admin"
    
    # API 요청인지 확인 (robeing-monitor API)
    is_api_request = path.startswith("api/") if path else False
    
    # API 요청은 JWT 검증 필요
    if is_api_request:
        try:
            user_uuid = get_verified_user(authorization)
            logger.info(f"Admin API request from user {user_uuid} to {target_url}")
        except HTTPException as e:
            logger.warning(f"Admin API request without valid JWT to {target_url}")
            raise e
    else:
        # HTML/정적 파일은 JWT 검증 없이 프록시
        logger.info(f"Admin static/HTML request to {target_url}")

    # Forward request
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method=request.method,
            url=target_url,
            headers=dict(request.headers),
            content=await request.body()
        )

        return Response(
            content=response.content,
            status_code=response.status_code,
            headers=dict(response.headers)
        )

2. Frontend JavaScript 수정

파일: /home/admin/frontend-base/admin-ui/index.html

변경 사항:

페이지 로드 시 localStorage에서 JWT 확인
JWT가 없으면 auth.ro-being.com/login으로 리다이렉트
JWT가 있으면 대시보드 표시
API 호출 시 JWT 우선 사용 (fallback: adminToken)

// JWT token check (Gateway 인증)
// localStorage에서 JWT 확인: 'auth_token' 또는 'token' 키 사용
const jwtToken = localStorage.getItem('auth_token') || localStorage.getItem('token');
let authToken = localStorage.getItem('adminToken'); // frontend-base 자체 인증 (fallback)

// JWT가 없으면 로그인 페이지로 리다이렉트
if (!jwtToken) {
    // 현재 URL 저장 (로그인 후 돌아오기 위해)
    const currentUrl = window.location.href;
    localStorage.setItem('admin_redirect_url', currentUrl);
    
    // auth.ro-being.com으로 리다이렉트
    window.location.href = 'https://auth.ro-being.com/login?redirect=' + encodeURIComponent(currentUrl);
    // 리다이렉트 후 실행 중단
    throw new Error('Redirecting to login');
}

// JWT가 있으면 대시보드 표시
if (authToken) {
    verifyToken();
} else {
    // JWT만 있고 frontend-base 자체 인증이 없으면 대시보드 표시
    showDashboard();
}

API 호출 함수 수정:

// API helper
async function apiCall(endpoint) {
    // JWT 우선 사용, 없으면 adminToken 사용 (fallback)
    const token = jwtToken || authToken;
    
    const response = await fetch(endpoint, {
        headers: {
            'Authorization': `Bearer ${token}`
        }
    });
    
    if (!response.ok) {
        // 401 에러 시 JWT 만료 또는 무효, 로그인 페이지로 리다이렉트
        if (response.status === 401) {
            localStorage.removeItem('auth_token');
            localStorage.removeItem('token');
            window.location.href = 'https://auth.ro-being.com/login?redirect=' + encodeURIComponent(window.location.href);
            throw new Error('Unauthorized - redirecting to login');
        }
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    return await response.json();
}

3. 테스트 코드 작성

파일: /home/admin/frontend-base/tests/test_admin_api.py

테스트 케이스:

Gateway /admin HTML 요청 - JWT 없이도 200 OK (HTML 반환)
Gateway /admin/api/* 요청 - JWT 없이 401 반환
frontend-base 직접 접근 - 정상 작동 확인

실행 결과:

=== Test 1: Gateway /admin HTML without JWT (예상: 200 OK) ===
Status: 200
Content-Type: text/html; charset=utf-8
✅ HTML 페이지 JWT 검증 없이 접근 가능 확인

=== Test 3: Gateway /admin/api/* without JWT (예상: 401) ===
Status: 401
✅ API 엔드포인트 JWT 검증 작동 확인

아키텍처 플로우

Before (401 에러)

사용자 → nginx → Gateway → JWT 검증 실패 → 401
(HTML도 받지 못함)

After (정상 동작)

1. HTML 요청:
   사용자 → nginx → Gateway → JWT 검증 없이 → frontend-base → HTML 반환 ✅

2. JavaScript 실행:
   - localStorage에서 JWT 확인
   - 없으면 → auth.ro-being.com/login 리다이렉트
   - 있으면 → 대시보드 표시

3. API 요청:
   사용자 → Gateway → JWT 검증 → robeing-monitor (51124:9024) ✅

검증

1. Gateway 상태

cd /home/admin/robeing-gateway
docker compose down && docker compose up -d --build
docker ps --filter "name=robeing-gateway"
# 출력: Up X seconds (healthy)

2. 엔드포인트 테스트

# HTML 요청 - JWT 없이도 200 OK
curl http://localhost:8100/admin
# <!DOCTYPE html>...

# API 요청 - JWT 없이 401
curl http://localhost:8100/admin/api/test
# {"detail":"Missing or invalid authorization header"}

# API 요청 - JWT 포함 시 정상
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8100/admin/api/test
# 정상 응답

3. 브라우저 테스트

URL: https://ro-being.com/admin
JWT 없이 접근:
1. HTML 페이지 로드 ✅
2. JavaScript 실행 → localStorage JWT 확인
3. JWT 없음 → auth.ro-being.com/login 리다이렉트 ✅
JWT 있이 접근:
1. HTML 페이지 로드 ✅
2. JavaScript 실행 → localStorage JWT 확인
3. JWT 있음 → 대시보드 표시 ✅
4. API 호출 정상 작동 ✅

설계 원칙

보안과 사용성 균형

HTML 페이지: 공개 접근 가능 (JavaScript에서 보안 처리)
API 엔드포인트: JWT 검증 필수 (서버 측 보안)

역할 분리

Gateway: 조건부 JWT 검증 (HTML vs API 구분)
Frontend JavaScript: 클라이언트 측 인증 체크 및 리다이렉트
Auth Server: 중앙화된 인증 제공

사용자 경험

HTML은 즉시 로드되어 빠른 응답
JavaScript에서 JWT 확인 후 필요시 리다이렉트
로그인 후 원래 페이지로 돌아오기 (redirect URL 저장)

교훈

설계 검증의 중요성

HTML 페이지와 API 엔드포인트의 보안 요구사항이 다름을 인식
모든 요청에 동일한 보안 정책 적용은 사용성을 해침

단계별 접근

HTML 로드 (공개)
JavaScript 실행 (클라이언트 측 보안)
API 호출 (서버 측 보안)

TDD 접근

테스트 코드 먼저 작성하여 요구사항 명확화
구현 → 테스트 → 검증 순서 준수

다음 단계

✅ Gateway 라우팅 수정 완료
✅ Frontend JavaScript 수정 완료
✅ 테스트 코드 작성 완료
⏳ 실제 배포 및 브라우저 테스트
⏳ 로그인 후 redirect URL 처리 확인

9.1 KiB Raw Blame History