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 으로 확정되었다.

이번 회차 확정 사항

• BARON-SSO 애플리케이션 유형은 Server-side app 으로 설정
• client_secret 을 사용하는 Authorization Code 기반 서버 처리 방식 사용
• 토큰 교환과 세션 생성은 브라우저가 아니라 서버에서 처리
• 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 분리 여부를 결정한다.

현재 확정된 방식

• 보안 수준: Server-side app
• 인증 플로우: 서버에서 Authorization Code 처리
• 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 기반 사용자 정보 파싱 구현
• 실패 시 예외 처리 및 사용자 안내 구현

구현 상세 체크리스트

• 브라우저 직접 토큰 저장 방식은 사용하지 않음
• callback 에서 서버가 token endpoint 호출
• 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 흐름도 그대로 유지할 수 있다.