egbim_homepage/BARON_SSO_QNA_MIGRATION_TASKS.md

# BARON-SSO 연동 및 Q&A 접근 전환 작업 목록

## 목표

- 외부 사용자는 기존 Descope 로그인을 계속 사용한다.
- 내부 사용자는 BARON-SSO 로그인으로 전환한다.
- 내부 사용자도 기존과 동일하게 Q&A 페이지를 조회, 작성, 수정, 댓글 작성할 수 있어야 한다.
- 로그인 공급자가 달라도 Q&A 는 동일한 세션 구조를 사용하도록 정리한다.

## 현재 확인된 전제

- 현재 Q&A 기능은 Descope 전용 세션 파일에 직접 의존한다.
- 국문 `egbim/` 와 영문 `eng/` 에 동일한 구조가 병렬로 존재한다.
- 내부/외부 사용자 판별은 현재 Q&A 작성 로직에서 이메일 도메인 기준으로 처리한다.
- 관리자 권한은 세션 파일 내부의 이메일 화이트리스트 기반이다.
- BARON-SSO 전용 콜백, 토큰 교환, 사용자 정보 매핑 로직은 현재 코드베이스에 별도로 구현되어 있지 않다.
- BARON-SSO 애플리케이션 보안 수준은 `Server-side app` 으로 확정되었다.

## 이번 회차 확정 사항

- [x] BARON-SSO 애플리케이션 유형은 `Server-side app` 으로 설정
- [x] `client_secret` 을 사용하는 Authorization Code 기반 서버 처리 방식 사용
- [x] 토큰 교환과 세션 생성은 브라우저가 아니라 서버에서 처리
- [ ] BARON-SSO claim 샘플 확보
- [ ] callback 엔드포인트 경로 확정
- [ ] 공통 auth bootstrap 파일 구조 확정

## 현재 영향 파일

### 공통 세션/인증 진입점

- `egbim/skin/member/basic/descope_session.php`
- `eng/skin/member/basic/descope_session.php`
- `egbim/skin/member/basic/descope_login.php`
- `eng/skin/member/basic/descope_login.php`
- `egbim/skin/member/basic/descope_logout.php`
- `eng/skin/member/basic/descope_logout.php`

### Q&A 주요 진입점

- `egbim/bbs/descope_qa_list.php`
- `egbim/bbs/descope_qa_detail.php`
- `egbim/bbs/descope_qa_write.php`
- `egbim/bbs/descope_qa_comment.php`
- `egbim/bbs/descope_qa_comment_update.php`
- `egbim/bbs/descope_qa_comment_delete.php`
- `egbim/bbs/descope_qa_delete.php`
- `egbim/bbs/descope_qa_status.php`
- `egbim/bbs/admin_guard.php`
- `eng/bbs/descope_qa_list.php`
- `eng/bbs/descope_qa_detail.php`
- `eng/bbs/descope_qa_write.php`
- `eng/bbs/descope_qa_comment.php`
- `eng/bbs/descope_qa_comment_update.php`
- `eng/bbs/descope_qa_comment_delete.php`
- `eng/bbs/descope_qa_delete.php`
- `eng/bbs/descope_qa_status.php`
- `eng/bbs/admin_guard.php`

## 1. 정책 확정

- [ ] 내부 사용자와 외부 사용자의 로그인 정책을 문서로 확정한다.
- [ ] 내부 사용자 판별 기준을 확정한다.
- [ ] 내부 사용자 판별을 이메일 도메인으로 유지할지, 별도 진입 버튼으로 분기할지 결정한다.
- [ ] 로그인 화면에서 외부용 Descope 와 내부용 BARON-SSO 를 어떻게 노출할지 결정한다.
- [ ] 국문 `egbim/` 와 영문 `eng/` 모두 동일 정책을 적용할지 확인한다.

### 정책 결정 시 확인 항목

- [ ] 내부 사용자 도메인 목록 확정
- [ ] 예외 계정 처리 방식 확정
- [ ] 관리자 계정 판단 기준 유지 여부 확정
- [ ] 로그인 실패 시 안내 문구와 리다이렉트 방식 확정

## 2. BARON-SSO 연동 정보 정리

- [ ] BARON-SSO OIDC 설정값을 확정한다.
- [ ] `client_id`, `client_secret`, `discovery_endpoint`, `issuer`, `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint` 를 운영값 기준으로 문서화한다.
- [ ] Redirect URI 를 실제 서비스 경로와 맞춘다.
- [ ] 운영 도메인이 `eg-bim.com` 인지 `eg-bim.co.kr` 인지 최종 확정한다.
- [ ] 로컬/개발/운영 환경별 Redirect URI 분리 여부를 결정한다.

### 현재 확정된 방식

- [x] 보안 수준: `Server-side app`
- [x] 인증 플로우: 서버에서 Authorization Code 처리
- [x] `client_secret` 필요
- [ ] PKCE 지원 여부 확인
- [ ] `scope` 목록 확정

### 확인 필요 항목

- [ ] 현재 등록된 Redirect URI: `https://eg-bim.com/auth/callback`
- [ ] 실제 애플리케이션에서 사용할 콜백 경로가 존재하는지 확인
- [ ] 사내망 또는 VPN 환경에서만 접근 가능한지 확인
- [ ] BARON-SSO 로그아웃 엔드포인트 제공 여부 확인
- [ ] 로컬 테스트용 Redirect URI 추가: `http://localhost:8088/auth/callback`

## 3. 공통 인증 계층 설계

- [ ] Descope 전용 세션 파일을 공급자 중립적인 공통 인증 bootstrap 구조로 분리한다.
- [ ] 로그인 공급자가 달라도 최종 세션 구조는 동일하게 맞춘다.
- [ ] Q&A 코드는 특정 공급자명을 몰라도 되도록 정리한다.
- [ ] 국문/영문 트리에서 인증 공통화 파일 위치를 통일한다.

### 권장 방향

- [ ] `descope_session.php` 를 바로 확장하지 말고 공통 auth loader 로 분리
- [ ] Descope 와 BARON-SSO 모두 동일한 `$_SESSION['user']` 구조를 채우도록 통합
- [ ] Q&A 는 공통 auth loader 만 include 하도록 변경
- [ ] 공급자별 쿠키 복원, 세션 복원, 권한 매핑은 내부 모듈로 캡슐화

### 세션 표준 구조 초안

- [ ] `$_SESSION['user']['userId']`
- [ ] `$_SESSION['user']['loginIds'][0]`
- [ ] `$_SESSION['user']['name']`
- [ ] `$_SESSION['user']['email']`
- [ ] `$_SESSION['user']['phone']`
- [ ] `$_SESSION['user']['customAttributes']`
- [ ] `$_SESSION['user']['roleNames']`
- [ ] 그누보드 연동용 `$_SESSION['ss_mb_id']`, `$_SESSION['ss_mb_level']`

## 4. BARON-SSO 인증 구현

- [ ] 로그인 시작 엔드포인트 구현
- [ ] state, nonce 저장 및 검증 구현
- [ ] callback 엔드포인트 구현
- [ ] authorization code 를 token 으로 교환하는 로직 구현
- [ ] id token 또는 userinfo 기반 사용자 정보 파싱 구현
- [ ] 실패 시 예외 처리 및 사용자 안내 구현

### 구현 상세 체크리스트

- [x] 브라우저 직접 토큰 저장 방식은 사용하지 않음
- [x] callback 에서 서버가 token endpoint 호출
- [x] callback 성공 후 서버 세션에 사용자 정보 저장
- [ ] OIDC discovery 자동 사용 여부 결정
- [ ] discovery 미사용 시 endpoint 고정값 사용
- [ ] 세션 고정 공격 방지용 session regenerate 적용 여부 확인
- [ ] callback 에서 CSRF 방지용 state 검증
- [ ] 토큰 검증 책임 범위 결정
- [ ] 토큰 만료와 재로그인 정책 정의

### Server-side app 기준 추가 작업

- [ ] callback 에서 `code`, `state`, `error` 파라미터 처리 규칙 정의
- [ ] token endpoint 요청 파라미터 목록 정리
- [ ] `client_secret` 저장 위치 확정
- [ ] 세션 생성 직후 `session_regenerate_id(true)` 적용
- [ ] 로그인 성공 후 이동할 기본 URL 확정
- [ ] 로그인 실패 시 복귀 URL 과 안내 문구 확정

## 5. 사용자 정보 매핑 규칙 정리

- [ ] BARON-SSO claim 샘플을 확보한다.
- [ ] BARON-SSO 의 사용자 식별자 중 무엇을 `loginIds[0]` 으로 쓸지 확정한다.
- [ ] 이름, 이메일, 전화번호, 회사, 계열사, 부서 claim 매핑 규칙을 정한다.
- [ ] BARON claim 에 없는 값은 기본값 또는 빈값 처리 기준을 정한다.

### 현재 Q&A 가 기대하는 값

- [ ] 내부 사용자 저장 시 `family_company`, `department` 사용
- [ ] 외부 사용자 저장 시 `company`, `department` 사용
- [ ] 작성자 식별은 `login_id` 기준
- [ ] 내 글 여부 판단도 `login_id` 기준

### 확인 필요 리스크

- [ ] BARON-SSO 가 이메일을 직접 주지 않는 경우 대응 필요
- [ ] 부서명 claim key 가 `team` 과 다를 가능성 확인 필요
- [ ] 계열사명 claim 이 `familyCompany` 와 다를 가능성 확인 필요
- [ ] 영문 사이트에서 표시명 영문화가 필요한지 검토

## 6. Q&A 접근 제어 변경

- [ ] Q&A 목록에서 로그인 사용자 식별이 공통 세션으로 동작하는지 확인
- [ ] Q&A 상세에서 비밀글 접근 제어가 내부 사용자에게도 동일하게 동작하는지 확인
- [ ] Q&A 작성에서 로그인 강제가 BARON-SSO 사용자에게도 정상 동작하는지 확인
- [ ] 댓글 작성, 수정, 삭제도 동일 세션 구조 기준으로 동작하는지 확인
- [ ] 관리자 상태 변경 기능이 정상 동작하는지 확인

### 변경 대상 포인트

- [ ] `require_once .../descope_session.php` 참조를 공통 auth bootstrap 으로 치환
- [ ] 로그인 여부 조건식이 특정 공급자 쿠키에 의존하지 않는지 점검
- [ ] 작성자 식별 키가 공급자별로 달라지지 않도록 통일
- [ ] 비로그인 사용자 공개글 조회 정책 유지 여부 확인

## 7. 관리자 권한 체계 정리

- [ ] 현재 이메일 화이트리스트 방식을 유지할지 결정한다.
- [ ] BARON-SSO role 또는 group claim 기반으로 바꿀지 결정한다.
- [ ] 관리자 표시 이름 가공 로직과 충돌이 없는지 확인한다.

### 권장 방향

- [ ] 1차 전환은 이메일 화이트리스트 유지
- [ ] 2차에서 BARON role 기반 권한 이관 검토
- [ ] 권한 기준은 국문/영문 공통으로 단일화

## 8. 로그인 화면 및 UX 변경

- [ ] 메인 헤더 또는 로그인 팝업에 내부 사용자용 BARON-SSO 진입 버튼 추가
- [ ] 외부 사용자용 기존 Descope 로그인 버튼 유지
- [ ] 로그인 실패 안내 문구를 공급자별로 구분할지 결정
- [ ] 내부 사용자가 Descope 로그인으로 잘못 진입했을 때 안내 문구 제공 여부 결정

### 권장 UX

- [ ] 버튼 2개 분리: `외부 사용자 로그인`, `사내 사용자 로그인`
- [ ] 최초 단계에서는 자동 도메인 판별보다 명시적 분기 우선
- [ ] 내부 사용자 안내 문구에 사내 계정 사용 정책 명시

## 9. 로그아웃 및 세션 종료 처리

- [ ] Descope 로그아웃은 기존 방식 유지
- [ ] BARON-SSO 로그아웃 처리 추가
- [ ] 로컬 세션 종료와 IdP 세션 종료를 분리할지 결정
- [ ] 로그아웃 후 재진입 시 자동 재로그인 여부 확인

### 점검 항목

- [ ] PHP 세션 제거
- [ ] Descope 관련 쿠키 제거
- [ ] BARON 관련 쿠키 또는 state 쿠키 제거
- [ ] 브라우저 백버튼 진입 시 인증 상태 오동작 여부 확인

## 10. 설정값 및 비밀정보 관리

- [ ] BARON-SSO 설정값을 코드 하드코딩 없이 분리한다.
- [ ] 운영/개발/로컬 설정 파일 구조를 정리한다.
- [ ] 민감정보가 저장소에 올라가지 않도록 관리 방식을 정한다.

### 체크리스트

- [ ] `client_secret` 는 환경변수 또는 비공개 설정 파일로 관리
- [ ] callback URL 도 환경별 분리
- [ ] issuer, endpoint 값도 환경별 override 가능하도록 구성
- [ ] 배포 문서에 설정 절차 추가

## 11. 테스트 시나리오

- [ ] 외부 사용자 Descope 로그인 후 Q&A 목록 조회
- [ ] 외부 사용자 Descope 로그인 후 Q&A 작성
- [ ] 내부 사용자 BARON-SSO 로그인 후 Q&A 목록 조회
- [ ] 내부 사용자 BARON-SSO 로그인 후 Q&A 작성
- [ ] 내부 사용자 BARON-SSO 로그인 후 댓글 작성
- [ ] 내부 관리자 BARON-SSO 로그인 후 상태 변경
- [ ] 비로그인 사용자 공개글 조회
- [ ] 비밀글 작성자 본인 접근
- [ ] 비밀글 타 사용자 접근 차단
- [ ] 로그아웃 후 접근 차단
- [ ] 국문 `egbim/` 검증
- [ ] 영문 `eng/` 검증

### 추가 확인 항목

- [ ] 모바일 브라우저 로그인 진입 확인
- [ ] 로그인 팝업 차단 이슈 여부 확인
- [ ] 세션 만료 후 재시도 흐름 확인
- [ ] 첨부파일 다운로드 권한 흐름 확인

## 12. 배포 및 롤백 계획

- [ ] BARON-SSO 기능 배포 순서를 정한다.
- [ ] 운영 반영 전 내부 사용자 테스트 계정으로 사전 검증한다.
- [ ] 장애 시 내부 사용자를 임시 우회시킬 방법을 준비한다.

### 권장 배포 순서

- [ ] 1차: 공통 auth bootstrap 도입
- [ ] 2차: BARON-SSO callback 및 세션 매핑 구현
- [ ] 3차: 로그인 UI 에 사내 사용자 버튼 노출
- [ ] 4차: 내부 사용자 실사용 테스트
- [ ] 5차: 운영 전환

### 롤백 포인트

- [ ] BARON-SSO 버튼 숨김만으로 즉시 차단 가능한지 확인
- [ ] 내부 사용자 임시 Descope 허용 스위치 필요 여부 검토
- [ ] 공통 auth bootstrap 에 공급자 fallback 허용 여부 검토

## 바로 실행할 우선순위

### P0

- [ ] 내부/외부 로그인 정책 확정
- [ ] BARON-SSO claim 샘플 확보
- [ ] Redirect URI 와 실제 콜백 경로 확정
- [ ] 공통 세션 구조 정의

## 다음 진행 항목

### 지금 바로 할 일

- [ ] BARON-SSO callback URL 을 실제 구현 경로로 확정한다.
- [ ] BARON-SSO 에서 내려주는 id token 또는 userinfo claim 샘플 1건을 확보한다.
- [ ] 공통 auth bootstrap 파일명을 확정한다.
- [ ] Descope 세션 구조와 BARON 세션 구조 매핑표를 작성한다.

### 다음 구현 순서

- [ ] 1단계: BARON 로그인 시작 엔드포인트 추가
- [ ] 2단계: BARON callback 엔드포인트 추가
- [ ] 3단계: callback 에서 공통 `$_SESSION['user']` 생성
- [ ] 4단계: Q&A 진입 파일들의 `descope_session.php` include 를 공통 auth bootstrap 으로 교체
- [ ] 5단계: 로그인 UI 에 사내 사용자 로그인 버튼 추가

### 구현 전에 확정되면 좋은 값

- [ ] 내부 사용자 기본 이동 페이지
- [ ] 로그인 성공 후 이동 페이지가 메인인지 Q&A 인지 결정
- [ ] 로그아웃 후 이동 페이지 결정
- [ ] BARON-SSO 에서 제공하는 부서, 계열사, 이메일 claim key 명칭 확정

### P1

- [ ] 공통 auth bootstrap 구현
- [ ] BARON-SSO callback 구현
- [ ] Q&A 진입점 공통 auth 로 치환
- [ ] 로그아웃 처리 추가

### P2

- [ ] 로그인 UI 개선
- [ ] 관리자 권한 체계 정리
- [ ] 영문 사이트 동기화
- [ ] 운영 문서와 배포 절차 정리

## 메모

- 현재 구조에서는 Q&A 비즈니스 로직보다 인증 세션 통합이 핵심 작업이다.
- 가장 안전한 방향은 BARON-SSO 사용자도 최종적으로 기존과 동일한 `$_SESSION['user']` 구조를 갖게 만드는 것이다.
- 이렇게 하면 Q&A 자체의 수정량을 줄이고, 외부 사용자용 Descope 흐름도 그대로 유지할 수 있다.