baron-sso/main-dev.md

개발 문서: 메인 프로젝트 Baron SSO 연동 작업

1. 연동 목표

Baron SSO(http://localhost:5000)를 통합 인증(SSO) 공급자로 사용하여 메인 프로젝트의 사용자 인증을 처리합니다. 사용자가 Baron SSO를 통해 성공적으로 인증하면, 메인 프로젝트는 JWT를 수신하여 로그인 상태를 유지하고, 보호된 백엔드 API에 접근할 수 있게 됩니다.

---

2. 작업 계획 (체크리스트)

Frontend

• Baron SSO 팝업창 실행 로직 구현:

  • 내용: '로그인' 버튼 클릭 시, window.open()을 사용하여 Baron SSO 로그인 페이지(http://localhost:5000)를 팝업창으로 엽니다.
  • 필요 이유: 사용자에게 익숙한 팝업창을 통해 소셜 로그인과 유사한 인증 경험을 제공합니다.

• JWT 수신을 위한 이벤트 리스너 추가:

  • 내용: Baron SSO 팝업창으로부터 JWT 토큰을 수신하기 위해 window.addEventListener('message', ...)를 구현합니다. Baron SSO는 인증 성공 시 postMessage를 통해 토큰을 전달할 것입니다.
  • 필요 이유: 부모 창(메인 프로젝트)과 자식 창(Baron SSO) 간의 안전한 통신 채널을 확보하여 인증 결과(JWT)를 전달받기 위함입니다.

• 인증 성공 후 처리 로직 구현:

  • 내용: 이벤트 리스너가 JWT를 성공적으로 수신하면 다음을 수행합니다.
    1. 수신한 JWT를 localStorage 또는 sessionStorage에 안전하게 저장합니다.
    2. 열려있는 Baron SSO 팝업창을 닫습니다. (popup.close())
    3. 애플리케이션의 상태를 '로그인 완료'로 변경하고, 사용자를 대시보드 등 로그인 후 페이지로 리디렉션합니다.
  • 필요 이유: 사용자의 로그인 상태를 애플리케이션 전반에 걸쳐 유지하고, 원활한 사용자 경험을 제공하기 위함입니다.

• API 요청 시 JWT 헤더 추가:

  • 내용: 메인 프로젝트의 백엔드 API를 호출하는 모든 요청의 Authorization 헤더에 저장된 JWT를 Bearer <token> 형식으로 포함하도록 API 클라이언트(e.g., axios, fetch)를 수정합니다.
  • 필요 이유: 백엔드에 현재 사용자가 인증되었음을 증명하고, 보호된 리소스에 접근 권한을 얻기 위함입니다.

Backend

• JWT 검증 미들웨어 구현:

  • 내용: API 요청의 Authorization 헤더에서 JWT를 추출하고, 유효성을 검증하는 미들웨어를 작성합니다. 검증 과정은 다음을 포함해야 합니다.
    1. 토큰의 서명을 Baron SSO와 공유하는 COOKIE_SECRET을 사용하여 확인합니다.
    2. 토큰의 만료 시간(exp)을 확인합니다.
  • 필요 이유: 인증되지 않은 사용자가 보호된 API 엔드포인트에 접근하는 것을 막는 핵심 보안 계층입니다.

• 보호된 라우트에 미들웨어 적용:

  • 내용: 사용자 정보가 필요하거나 인증된 사용자만 접근해야 하는 모든 API 라우트(e.g., /api/me, /api/posts)에 위에서 구현한 JWT 검증 미들웨어를 적용합니다.
  • 필요 이유: 특정 API들을 선택적으로 보호하여 서비스의 보안 수준을 높입니다.

• (선택) 사용자 정보 컨텍스트 주입:

  • 내용: 미들웨어에서 토큰 검증이 성공하면, 토큰의 claims(e.g., sub에 저장된 전화번호)에서 사용자 식별 정보를 추출하여 해당 요청의 컨텍스트(context)에 담아줍니다.
  • 필요 이유: 각 API 핸들러가 현재 요청을 보낸 사용자가 누구인지 쉽게 파악하고, 해당 사용자에 맞는 비즈니스 로직을 처리할 수 있도록 하기 위함입니다.

---

3. 연동 후 인증 플로우: 시퀀스 다이어그램

sequenceDiagram
    participant 사용자
    participant MainAppFE as 메인 프로젝트 (FE)
    participant BaronSSO as Baron SSO (팝업)
    participant MainAppBE as 메인 프로젝트 (BE)

    Note over 사용자, BaronSSO: 1. 로그인 요청 및 인증
    사용자->>MainAppFE: 로그인 버튼 클릭
    MainAppFE->>BaronSSO: 팝업창으로 SSO 페이지 실행
    BaronSSO-->>사용자: SMS 인증 등 수행
    BaronSSO->>BaronSSO: 인증 성공 후 JWT 생성
    BaronSSO-->>MainAppFE: `postMessage`로 JWT 전달

    Note over MainAppFE, MainAppBE: 2. 로그인 처리 및 API 접근
    MainAppFE->>MainAppFE: JWT 수신 및 저장
    MainAppFE->>MainAppFE: 팝업창 닫기 & 대시보드 이동
    
    사용자->>MainAppFE: 데이터 요청 (e.g., 내 정보 보기)
    MainAppFE->>MainAppBE: API 요청 (Authorization: Bearer JWT 헤더 포함)
    
    MainAppBE->>MainAppBE: JWT 검증 미들웨어 실행
    alt JWT 유효
        MainAppBE->>MainAppBE: API 로직 처리
        MainAppBE-->>MainAppFE: 요청한 데이터 응답 (e.g., 사용자 정보)
    else JWT 유효하지 않음
        MainAppBE-->>MainAppFE: 401 Unauthorized 에러 응답
    end

    MainAppFE->>사용자: 수신한 데이터 표시 또는 에러 처리