신규 포탈 프로비저닝 입력값과 자동 설정값
상태: 설계 문서(미구현) — 자동 생성은 아직 구현되지 않았다. 배포 대상은 배포 플랫폼 또는 온프레미스이며, 플랫폼 전용 API·URL은 계약에 넣지 않는다(
UiPlatform/docs/PLATFORM_NAMING.md).
적용 범위
이 문서는 DirectoryService 관리자 화면의 설정 → 포탈 연동 설정 → 신규 포탈 자동 생성에서 사용하는 입력값을 정의한다. 생성 작업은 비공개 GitHub 템플릿 저장소를 기준으로 시작하며, 배포 플랫폼 또는 온프레미스 배포 대상을 선택할 수 있다. 생성 전에는 공통 포탈 프레임, 테마, 중앙 연동 항목 및 수정 가능한 기본 메뉴 Seed를 시뮬레이션으로 확인하고, 확인 절차를 거쳐 실제 생성으로 진행한다. 1 2
운영자가 입력하는 값
현재 생성 API의 입력 계약은 아래와 같다. 필수 표시는 API가 반드시 받는 값이며, 온프레미스 배포의 경우에는 실제 운영 가능성을 위해 공개 URL과 내부 배포 대상도 입력해야 한다.
| 화면 항목 | API 필드 | 필수 여부 | 규칙과 사용처 |
|---|---|---|---|
| 포탈 식별자 | portalId | 필수 | 영문 소문자·숫자·하이픈으로 된 2~64자 값이다. 중앙 OAuth client ID, 동기화 식별자, 암호화 컨텍스트, 테마 저장 키의 기준이 된다. |
| 포탈 표시명 | portalName | 필수 | 관리 화면과 중앙 로그인 제목에 표시된다. 1~120자로 입력한다. |
| 배포 공급자 | deploymentProvider | 필수 | 현재 RENDER 또는 ON_PREM을 선택한다. 공급자 드라이버가 배포 대상 생성과 비밀값 전달 방식을 결정한다. |
| GitHub 저장소 소유자/조직 | repositoryOwner | 필수 | 새 비공개 저장소를 받을 GitHub 사용자명 또는 조직명이다. 영문·숫자·하이픈 1~38자 규칙을 따른다. |
| 저장소 이름 | repositoryName | 선택 | 비워두면 포탈 식별자를 사용한다. 생성되는 비공개 GitHub 저장소 이름이며 2~100자 규칙을 따른다. |
| 저장소 설명 | description | 선택 | 비워두면 <포탈명> portal을 사용한다. 생성되는 GitHub 저장소 설명이다. |
| 로그인 callback 경로 | redirectPath | 선택 | 비워두면 /auth/callback을 사용한다. 반드시 /로 시작해야 하며, 최종 포탈 URL과 결합해 중앙 로그인 redirect URI로 등록한다. |
| 포탈 기본 URL | baseUrl | 배포 플랫폼 선택 시 선택, 온프레미스 선택 시 사실상 필수 | 온프레미스 포탈의 공개 URL을 지정한다. 배포 플랫폼는 공급자가 생성한 URL을 최종 값으로 사용한다. |
| 온프레미스 배포 대상 | onPremiseTarget | 온프레미스 선택 시 사실상 필수 | 고객사 내부의 Secret Manager·배포 에이전트·Kubernetes namespace·VM 배포 채널 등을 식별하는 비밀값 없는 라벨이다. 예: prod-k8s/process-center. |
| 배포 플랫폼 Workspace Owner ID | renderOwnerId | 배포 플랫폼 선택 시 필수 | 배포 플랫폼 Workspace의 사용자 또는 팀 식별자다. 배포 플랫폼 선택 시에만 표시·전달한다. |
| 배포 플랫폼 리전 | renderRegion | 배포 플랫폼 선택 시 필수 | 예: singapore. 배포 플랫폼 선택 시에만 표시·전달하며, 서비스 요청의 리전으로 사용한다. |
비밀값은 입력하지 않는다. GitHub·배포 플랫폼·온프레미스 인프라의 장기 토큰, SSH 키, Secret Manager 자격증명은 관리자 웹 폼이나 문서에 입력·기록하지 않는다.
repositoryOwner,renderOwnerId,renderRegion은 비밀값이 아닌 이번 요청의 운영 선택값이므로 요청 스냅샷에만 기록한다. GitHub·배포 플랫폼 API 연결 비밀값은 DirectoryService 서버에서만 관리하고, 온프레미스 비밀값은 고객사 내부 시스템에서만 관리한다. 1
시스템 관리자가 서버에 설정하는 값
아래 값은 신규 포탈을 만드는 운영자가 매번 입력하는 값이 아니라 DirectoryService 운영 환경에 한 번 설정하는 연결 정보다. 실제 값은 서버 비밀값 저장소에만 둔다.
| 서버 설정 | 보안 분류 | 사용 목적 | 적용 범위 | |---|---|---| | PORTAL_PROVISIONING_GITHUB_TOKEN | 서버 Secret | 비공개 템플릿 저장소에서 새 비공개 저장소를 생성한다. | 모든 공급자 | | PORTAL_PROVISIONING_TEMPLATE_REPOSITORY | 서버 전역 설정 | owner/repository 형태의 포탈 템플릿 저장소다. 현재 기준 템플릿은 hohyun94/portal-foundation-template이다. | 모든 공급자 | | DIRECTORY_SERVICE_PUBLIC_URL | 서버 전역 설정 | 새 포탈이 DirectoryService API·중앙 로그인에 연결할 공개 주소다. | 모든 공급자 | | 배포 플랫폼 API 키 | 서버 Secret | 배포 플랫폼 서비스 생성·환경변수 주입·배포 요청에 사용한다. | 배포 플랫폼 |
PORTAL_PROVISIONING_GITHUB_OWNER, PORTAL_PROVISIONING_RENDER_OWNER_ID, PORTAL_PROVISIONING_RENDER_REGION, PORTAL_PROVISIONING_RENDER_ENVIRONMENT_ID는 더 이상 신규 생성 요청에 사용하지 않는다. 화면 입력 전환 버전의 배포와 확인이 끝난 뒤 제거한다.
생성 시 자동으로 적용되는 값
포탈 식별자와 공급자를 입력하면 시스템은 다음 구성을 자동으로 만든다. 운영자는 생성 결과에서 상태와 일회성 API Key만 확인하며, API Key 원문은 목록·감사 로그·재조회 결과에 저장되지 않는다. 1
| 자동 적용 영역 | 생성 결과 |
|---|---|
| 소스 코드 | 선택된 비공개 GitHub 템플릿에서 새 비공개 저장소를 만든다. |
| 중앙 로그인 | portalId를 client ID로 등록하고 <배포 URL><redirectPath>를 redirect URI로 설정한다. |
| 공통 UI | @hohyun94/portal-foundation@^0.5.0 공통 UI 구독을 활성화한다. |
| 메뉴 관리 | 템플릿에 홈·업무 공간·관리자·내 정보 기본 메뉴와 공통 메뉴 관리 화면을 포함한다. 포탈별 메뉴 데이터는 해당 포탈이 저장·감사한다. |
| 사용자·조직 | DirectoryService 동기화를 활성화하고 기본 동기화 주기를 설정한다. |
| 전문용어 사전 | 중앙 전문용어 사전의 실시간 조회를 활성화한다. |
| 최소 권한 Key | directory:read, directory:sync, directory:crypto, glossary:read 범위의 초기 기계 Key를 발급한다. |
| 암호화 | DirectoryService의 포탈별 컨텍스트 기반 Envelope Encryption 계약을 사용하도록 준비한다. 포탈에 마스터 키는 전달하지 않는다. |
| 테마 | 포탈별 테마 저장 키를 만들고 공통 UI 라이트·다크 테마 계약을 사용한다. |
| 운영 이력 | 생성 단계, 저장소·배포 대상 참조, 복구 안내와 오류 요약을 기록한다. |
공급자별 차이
| 항목 | 배포 플랫폼 | 온프레미스 |
|---|---|---|
| 서비스 생성 | DirectoryService가 배포 플랫폼 API로 생성한다. | 고객사 내부 배포 대상은 생성하지 않는다. |
| 환경변수 전달 | DirectoryService가 배포 플랫폼 환경변수로 주입하고 재배포를 요청한다. | 생성 직후 표시되는 일회성 Key와 환경변수 이름을 고객사 내부 Secret Manager 또는 배포 에이전트에 적용한다. |
| 배포·Health | 배포 플랫폼 재배포 및 health endpoint 확인 흐름을 사용한다. | 고객사 CI/CD 또는 배포 에이전트가 배포하고 health endpoint를 확인한다. |
| 장기 인프라 비밀값 | DirectoryService 서버 비밀값에만 둔다. | DirectoryService에 저장하지 않는다. |
배포 플랫폼 자동 생성은 항상 Free 인스턴스로 고정된다. DirectoryService 화면에는 유료 플랜, 디스크, 애드온을 고르는 선택지를 두지 않는다. 유료 전환이 필요하면 생성 후 배포 플랫폼 Dashboard에서 서비스 인스턴스 유형을 직접 변경한다. 배포 플랫폼 Free 웹 서비스는 15분 유휴 후 중지될 수 있고, 로컬 파일시스템은 지속되지 않으며, 월별 무료 사용량 한도가 있으므로 운영용 영속 저장소를 서비스 로컬 디스크에 두지 않는다. [4]
생성 전 메뉴 프리뷰와 기본 메뉴 Seed
현재 생성 입력에는 메뉴 항목 자체를 입력하지 않는다. 대신 운영자는 생성 전 시뮬레이션에서 포탈 프레임과 수정 가능한 최소 기본 메뉴 Seed를 확인하고 확인 상자를 선택한다. 생성된 포탈에는 공통 메뉴 관리 화면이 포함되며, 이후 메뉴명·경로·아이콘·순서·노출 정책·최소 scope는 해당 포탈의 데이터로 저장한다. 메뉴의 실데이터는 포탈별로 관리하고, Portal Foundation은 메뉴 모델·관리 UI·렌더링 계약만 공통 제공한다. 3