Platform Docs

Appearance

포털 호출 키 발급·등록 (2026-10-17) ​

1. 왜 바꿨나 ​

실제 운영에서 포털마다 배포 플랫폼이 달랐고, 신규 포털도 이 콘솔의 자동 구축 화면을 쓰지 않고 대상 플랫폼에서 직접 만들고 있었다. 그래서 콘솔의 배포 연계(배포 대상 등록·자동 전달· 적용 상태 확인·전달 이력)는 의미가 없어졌다.

대신 콘솔이 할 일을 키 발급과 등록 안내로 좁혔다.

  • 대상 포털이 사용할 포털 호출 키를 발급한다.
  • 키 원문을 한 번만 보여 주고, 어느 환경변수에 넣어야 하는지 플랫폼별 예시로 안내한다.
  • 적용 확인과 기존 키 정리는 관리자가 대상 플랫폼과 STEP 2 키 등록 화면에서 직접 한다.
  • STEP 1 연동 포털 등록은 포털 정보만 저장하고, 키는 STEP 2 키 등록에서 별도로 등록·발급한다.

2. 화면 구조 ​

포털 연동 설정
├─ 구간 탭: [포털]  [포털 접속 권한]
└─ 포털 구간 (기본 UI)
   STEP 1 연동 포털 등록
       등록된 포털 목록
       └ 신규등록 → 포털 등록 레이어 팝업
   STEP 2 키 등록
       등록된 키 목록
       ├ 기존 키 등록 → 기존 키 등록 레이어 팝업
       └ 신규등록     → 새 키 발급 레이어 팝업
                        발급 직후 1회 원문 + 등록 위치 안내

3. 발급·등록 절차 ​

발급 전제 — 콘솔 서버의 암호화 키 STEP 2 신규등록은 키 원문을 AES-256-GCM envelope 로 DB에만 보관합니다. 콘솔 서버에 PORTAL_CONSOLE_ENVELOPE_MASTER_KEY(32바이트 Base64)가 없거나 형식이 틀리면 발급 팝업이 412와 함께 설정 안내를 보여 주고 발급 버튼이 비활성화됩니다. openssl rand -base64 32로 만들고 배포 플랫폼의 secret 으로 넣은 뒤 콘솔을 재기동하세요. 키를 회전할 때는 이전 값을 PORTAL_CONSOLE_ENVELOPE_LEGACY_MASTER_KEYS에 남겨 기존 암호문을 계속 읽을 수 있게 합니다.

현재 상태는 STEP 2 키 등록 목록 상단의 암호화 ON / 암호화 설정 필요 배지로 확인합니다. 별도 보안·암호화 메뉴는 2026-10-17 제거했고, 키 버전·레거시 키 수·관측 이력은 서버 API (settings.encryptionStatus·settings.encryptionHistory)와 감사 로그에 남습니다.

  1. STEP 1의 신규등록에서 대상 포털을 등록한다. (client_id, 기본 URL, callback)
    • STEP 1은 포털 정보만 저장하며 키를 자동 발급하지 않는다. 키는 STEP 2에서 처리한다.
  2. STEP 2의 신규등록에서 포털을 고르고 필요한 최소 scope만 선택해 키를 발급한다. 포털이 이미 쓰는 키가 있으면 기존 키 등록에서 그 원문을 등록한다.
  3. 발급 직후 표시되는 PORTAL_CONSOLE_API_KEY=dpk_... 원문을 복사한다.
    • 이 원문은 팝업을 닫거나 새로고침하면 다시 볼 수 없다.
  4. 대상 포털 서버의 환경변수에 등록한다. (브라우저·프론트엔드 번들 금지)
  5. 서버를 재시작하거나 재배포한다.
  6. 포털에서 콘솔 API를 호출해 200 응답을 확인한다.
  7. 새 키가 실제로 쓰이는 것을 확인한 뒤 STEP 2에서 그 키를 열어 **「이 키만 남기기」**로 기존 키를 정리한다.

적용 전에 기존 키를 내리면 포털이 401로 멈춘다. 순서를 지킨다.

4. 대상 포털에 필요한 값 ​

이름어디서비고
PORTAL_CONSOLE_API_KEYSTEP 2 신규등록 결과정본 이름. 발급 원문은 1회만 표시
PORTAL_CONSOLE_URL이 콘솔의 주소STEP 2 안내가 현재 origin으로 보여 준다
PORTAL_JWT_SECRET콘솔과 같은 값보안상 화면에 표시하지 않는다
client_id · callbackSTEP 1 등록 정보포털 앱 설정과 같아야 한다

5. 플랫폼별 등록 예시 ​

.env ​

dotenv
PORTAL_CONSOLE_API_KEY=dpk_...
PORTAL_CONSOLE_URL=https://directory.example.com

Docker Compose ​

yaml
services:
  <portal-service>:
    environment:
      PORTAL_CONSOLE_API_KEY: ${PORTAL_CONSOLE_API_KEY}
    # 또는 env_file: .env

Coolify ​

대상 서비스 → Environment Variables에 PORTAL_CONSOLE_API_KEY를 추가하고 Redeploy한다.

Kubernetes ​

bash
kubectl create secret generic portal-console-key \
  --from-literal=PORTAL_CONSOLE_API_KEY=dpk_... -n <namespace>
yaml
envFrom:
  - secretRef:
      name: portal-console-key

systemd ​

ini
# /etc/systemd/system/<portal>.service.d/portal-console.conf
[Service]
Environment="PORTAL_CONSOLE_API_KEY=dpk_..."
Environment="PORTAL_CONSOLE_URL=https://directory.example.com"
bash
sudo systemctl daemon-reload
sudo systemctl restart <portal>

6. 제거한 것과 남긴 것 ​

  • 화면에서 제거: 자동 구축 진입점·미리보기, 배포 대상 목록/폼, 자동 전달, 적용 상태 확인, 자격증명 전달 이력, R2 자격증명 섹션.
  • 서버·DB: 기존 데이터 보존을 위해 API와 테이블은 남겨 두었다. 다만 발급 시 자동 전달은 더 이상 호출하지 않는다. R2 발급·전달 서버 경로는 FileStore 등 다른 소비자를 위해 유지한다.

7. 보안 계약 ​

  • 키 원문은 issuePortalCredential 응답에서 한 번만 반환한다. 목록 조회는 메타데이터만 반환한다.
  • 원문은 DB에 AES-256-GCM 암호문으로만 저장하고, 감사 로그에는 식별자만 남긴다.
  • 화면은 원문을 저장소(localStorage/sessionStorage)나 로그에 남기지 않는다.

8. 검증 ​

  • pnpm check 0 · pnpm test 562건 통과 · pnpm build 성공.
  • 브라우저(Chromium)에서 실제 콘솔 화면으로 STEP 2 신규등록 → 1회 원문/등록 안내 표시까지 확인.
  • ?tab=settings&section=integration에서 자동 구축·배포·R2 문구가 사라졌고, ?tab=portal-provisioning은 포털 목록으로 흡수되는 것을 확인.