포털 도메인·URL 운영 설정

목적

Directory Service 관리자 화면의 도메인·URL 설정 탭은 외부 포털의 공개 기본 주소와 중앙 로그인 callback 주소를 관리한다. 포털의 client_id, 표시 이름, 활성 상태, 허용 callback URL 목록을 한 곳에서 변경할 수 있으므로 도메인 변경 시 코드를 수정하거나 배포 환경의 URL 상수를 직접 편집할 필요가 없다.

보안 경계

공개 URL과 callback URL은 관리자 전용 tRPC 절차로만 변경한다. 저장 시 기본 URL과 callback URL은 HTTPS를 요구하며, 로컬 개발 환경의 localhost와 127.0.0.1만 HTTP를 허용한다. URL에 사용자명, 비밀번호, fragment를 넣을 수 없고 callback URL은 중복을 제거한다. authorization 요청은 저장된 전체 URL과 정확히 일치할 때만 허용한다.

DB 접속 주소, DB 계정, API Key, JWT secret, 비밀번호와 같은 비밀값은 portal_configurations에 저장하지 않는다. DATABASE_URL은 Secret 환경변수로 관리하며 관리자 화면에는 연결 host와 database 이름만 마스킹된 상태로 표시한다. 자격증명 교체는 프로젝트 Secret 관리에서 수행하고 서버 재시작 후 연결 상태를 확인한다.

데이터 모델

portal_configurations는 portal_id를 primary key로 사용한다. client_id는 unique이며, base_url은 포털의 공개 기본 주소, redirect_uris는 JSON 배열로 저장한다. enabled=false인 설정은 중앙 로그인에서 제외된다. file_store_enabled는 해당 포털의 첨부파일 연계 사용 여부이며, 활성화할 때 file_store_consumer_id는 FileStore에 등록된 consumerId와 정확히 일치해야 한다. FileStore의 backend, bucket, endpoint, secret과 세부 파일 정책은 PortalConsole에 저장하지 않는다. 포털 로그인 로고는 아이콘(login_logo_icon), 외부 URL(login_logo_url), 업로드 이미지(login_logo_data base64 · login_logo_content_type)로 관리하며, 업로드 이미지는 DB에 저장해 저장소 의존 없이 소비 포털에 data URL로 내려보낸다. 변경과 비활성화는 directory_audit_logs의 OPERATIONS 이벤트로 기록한다.

관리자 사용 절차

관리자 화면에서 도메인·URL 설정을 열고 포털을 선택한다. 포털의 기본 도메인이 변경되면 포털 기본 URL과 허용 callback URL을 함께 수정하고 저장한다. callback은 한 줄에 하나씩 입력할 수 있다. 변경 후 외부 포털의 callback 구현 경로와 실제 배포 URL이 동일한지 확인한다. 포털을 폐기하거나 중앙 로그인을 잠시 차단할 때는 로그인 설정 비활성화를 사용한다.

기본값과 DB 설정

초기 배포에는 PORTAL_LOGIN_CLIENTS_JSON이 기본값으로 사용될 수 있다. 동일한 client_id가 DB에 존재하면 관리자 화면에서 저장한 DB 설정이 환경변수 기본값보다 우선한다. DB 설정을 비활성화하면 해당 client는 환경변수 기본값으로 되살아나지 않도록 중앙 인증 병합 로직에서 DB override를 우선한다. 새 포털은 관리자 화면에서 DB 설정으로 등록할 수 있다.