Momento 엔터프라이즈 관리자 가이드 (Admin & Security Guide)

1. 시스템 아키텍처 및 부트스트랩 (Bootstrap)

Momento 컨테이너 프로세스는 3개의 필수 환경변수와 1개의 권장 환경변수만을 통해 최소 인프라로 구동됩니다.

# .env 환경 설정
MOMENTO_POSTGRES_DSN=postgres://momento:Secr3tPass@10.10.20.5:5432/momento?sslmode=disable
MOMENTO_BOOTSTRAP_ADMIN=admin@corporate.internal
MOMENTO_BOOTSTRAP_ADMIN_PASSWORD=SuperSecretAdminPassword123!
# 권장: 발급한 키를 암호화 저장해 재기동 후에도 다시 조회할 수 있게 합니다.
MOMENTO_ENCRYPTION_KEY=$(openssl rand -base64 32)

설정 원칙 (Design Principles):
그 밖의 모든 공개 URL, Keycloak OIDC Client 정보, Claim Mapping, PII 차단 필터, CIDR 망 대역은 DB에 저장되는 동적 관리자 설정입니다. 부트스트랩 비밀번호는 최초 관리자 계정 생성 시에만 사용되며 기존 계정을 덮어쓰지 않습니다.

1.1 비밀값 암호화 (MOMENTO_ENCRYPTION_KEY)

MOMENTO_ENCRYPTION_KEY를 설정하면 개인 API key, Site Tracking Key, Server API Key, OIDC Client Secret, Delivery Channel Header를 AES-256-GCM으로 암호화해 저장합니다. 값은 32 byte base64/hex 또는 16자 이상 passphrase를 허용하며, 플랫폼이 공용으로 주입하는 ENCRYPTION_KEY도 alias로 인식합니다.

2. Keycloak OIDC SSO 연동 및 RBAC 매핑

Momento는 PKCE(S256)가 적용된 표준 OIDC(OpenID Connect) SSO 통합을 지원합니다.

2.1 Keycloak Client 구성

  1. Keycloak Admin Console에서 momento-web Client ID 생성.
  2. Valid Redirect URIs 설정: https://momento.internal/api/v1/auth/oidc/callback
  3. Access Token Claim Mappers에 groups 및 roles 파싱 규칙 추가.

2.2 RBAC (Role-Based Access Control) 권한 매트릭스

역할 (Role) 개요 대시보드 쿼리 빌더 퍼널/경로 분석 사이트·보존 정책 PII 룰 변경 사용자·네트워크 감사 로그
Super Admin / Organization Admin ✅ ✅ ✅ ✅ ✅ ✅ ✅
Workspace Admin ✅ ✅ ✅ 소속 Workspace만 ❌ ❌ ✅
Analyst ✅ ✅ ✅ ❌ ❌ ❌ ❌
Viewer ✅ 조회 조회 ❌ ❌ ❌ ❌

PII 룰, 네트워크 망, 사용자 계정은 배포 전체에 적용되므로 조직 관리자 이상만 변경합니다(v0.33.1). 그 이전에는 Workspace 관리자도 변경할 수 있었고, 자기 역할을 최고 관리자로 올릴 수도 있었습니다.

Workspace 관리자의 사이트 관리(설정 변경, 키 회전, 삭제)는 자신이 속한 Workspace의 사이트로 한정됩니다(v0.33.0). 그 이전에는 다른 Workspace의 사이트도 대상이 됐습니다.

역할과 무관하게 자기 역할은 바꿀 수 없고, 자기보다 높은 역할은 부여할 수 없습니다. 최고 관리자도 스스로를 강등할 수 없습니다 — 배포에 관리자가 하나도 남지 않는 상태를 막기 위해서입니다.

2.1.9 릴리즈 자산이 누락되지 않는지

오프라인 설치는 릴리즈 자산(momento-vX.Y.Z.tar.gz와 체크섬)에 의존합니다. 태그를 밀면 릴리즈 워크플로가 실행되지만, 그 트리거는 한 번뿐이라 플랫폼 장애 시 유실될 수 있습니다.

Release reconciliation 워크플로가 매시간 최근 7일 태그와 릴리즈를 대조해, 릴리즈가 없거나 자산이 두 개가 아니면 릴리즈 워크플로를 다시 실행합니다. 수동으로 실행할 수도 있습니다.

2.2.0 보존 정책이 실제로 적용되는 범위

항목 적용
Raw Event (월) 적용 — 기간이 지난 Raw Event 삭제
Session (월) 적용 — Session 요약과 Visitor↔Session 색인(visitor_sessions) 둘 다
신원 (Visitor ID ↔ User ID) 적용 — v0.32.4부터 남은 이벤트·세션이 없는 방문자의 매핑과 per-visitor 집계 삭제
집계 (월) 적용 — 일별 집계 3종에서 기간이 지난 날짜 삭제. 비우면 무기한 보관
Debugger / Dead Letter (일) 적용
Realtime (시간) 적용되지 않음 — 별도의 Realtime 저장소가 없어 삭제 대상이 없습니다. API 호환을 위해 값은 계속 저장됩니다

집계 보존은 v0.29.0부터 적용됩니다. 이전에는 값을 저장만 하고 읽지 않아, 기간을 설정해도 일별 집계가 무기한 보관됐습니다.

일별 집계 중 방문자·세션 테이블은 하루에 방문자 한 명당 한 행이고 행마다 Visitor ID와 User ID가 있습니다. 집계 기간을 비워 두면 Raw Event가 삭제된 뒤에도 사람 단위 기록이 남습니다.

Visitor↔Session 색인은 v0.34.35부터 Session 보존기간을 따릅니다. 그 이전에는 어떤 보존 작업도 이 테이블에서 행을 지운 적이 없어, Raw Event와 Session이 사라진 뒤에도 Visitor ID·Session ID·User ID와 최초/최근 시각이 무기한 남았습니다. 개인 단위 삭제(개인정보 요청)는 파생 테이블을 재구축하므로 영향이 없었고, 기간 기반 보존만 이 테이블을 지나쳤습니다.

관리 ➔ 보존 정책 화면 상단이 직전 보존 작업을 보고합니다 — 실행 시각, 소요 시간, 테이블별 삭제 행 수, 그리고 실패했다면 그 원인. 이 기록은 v0.32.6부터 남습니다. 이전에는 정책과 수정 시각만 보였고 실패는 stderr 로그 한 줄로 끝났으므로, 로그 수집이 없는 폐쇄망에서는 한 달째 실패하는 작업과 삭제 대상이 없는 작업을 구분할 방법이 없었습니다. 삭제 대상이 없었던 회차도 “완료 · 0행”으로 보고되므로, 화면이 조용한 것과 작업이 멈춘 것이 구분됩니다. 기록은 최근 200회만 유지됩니다.

보존 작업은 매시간 무인으로 돌며, 테이블마다 2만 행씩 나눠 삭제하고 각 배치를 즉시 커밋합니다. 정책을 크게 줄인 직후처럼 삭제 대상이 많을 때도 진행한 만큼은 남으므로, 재기동이나 statement timeout으로 중단되어도 다음 시간에 이어서 수렴합니다. 한 번에 삭제하던 v0.32.4까지는 완료 전에 중단되면 아무 진행도 남지 않았습니다.

2.2.1 삭제와 보존의 검증 범위

개인정보 삭제는 규정 준수 약속이므로 통합 테스트로 확인합니다. user_id 모드 삭제 후 raw_events, sessions, visitors, visitor_sessions, visitor_identities, identified_users, daily_site_visitors, daily_site_sessions 여덟 개 테이블에 잔존 행이 없고, 같은 사이트의 다른 사람 데이터는 남아 있는지 확인합니다. visitor, period, property 모드도 각각 경계 밖 데이터 보존과 property만 제거되는지 확인합니다.

Retention은 사이트별 정책을 적용해 정책 밖 데이터가 삭제되고 정책 안 데이터가 유지되는지, Aggregate 재집계는 큐가 비고 실패 작업이 없는지 확인합니다.

2.3 분석 쿼리 보호

최대 정확 조회 기간은 쿼리 빌더뿐 아니라 모든 분석 리포트 화면에 적용됩니다. v0.28.0 이전에는 쿼리 빌더 한 곳에서만 확인해, 한도를 낮춰도 무거운 리포트 화면은 제한 없이 조회되고 있었습니다. 콘솔의 기간 선택지도 이 한도를 반영하므로 거절될 기간은 애초에 제시되지 않습니다.

대화형 분석 조회(방문자 인사이트, 이상 감지, 기여도, 방문자 검색·추적, Funnel)는 25초 제한 아래에서 실행됩니다. 초과하면 연결을 붙잡아 두지 않고 504 QUERY_TIMEOUT으로 즉시 끝나며, 기간 축소·Segment 적용·Scheduled Report 사용을 안내합니다. 요청이 취소되면 데이터베이스 쿼리도 함께 취소됩니다.

방문자 인사이트 보고서는 서로 독립적인 8개 조회를 동시 실행 4개 상한으로 병렬 수행합니다. 연결 풀(20)을 한 요청이 소진하지 않도록 상한을 두었고, 하나가 실패하면 나머지를 취소해 부분 결과를 완성된 보고서로 표시하지 않습니다.

이상 감지 기준선은 일별 Rollup(daily_site_metrics, daily_site_visitors, daily_site_sessions)에서 계산합니다. 평가 대상 날짜의 Rollup이 아직 없으면 그때만 Raw Event를 읽습니다. 따라서 Aggregate가 밀려 있으면 이상 감지가 느려질 수 있으며, 관리 → Aggregate Manager에서 재집계 상태를 확인하십시오.

013_analytical_indexes.sql은 sessions 인덱스와 방문자 검색용 pg_trgm 인덱스를 만듭니다. 세션 수가 많은 기존 설치에서는 이 마이그레이션이 최초 기동 시 수 초에서 수 분 걸릴 수 있습니다. pg_trgm 확장을 만들 권한이 없으면 인덱스 생성을 건너뛰고 순차 검색으로 동작합니다.

3. 개인정보 (PII) 필터 & URL 마스킹

수집기(Durable Collector)는 Inbox에 저장하기 전 개인정보 정책을 적용합니다. 기본 정책은 개인정보로 지정된 Property key를 중첩 객체와 Item 배열까지 제거하며, URL Query String과 Fragment를 제거합니다. Query String 수집을 명시적으로 활성화한 경우에만 관리자 목록의 Parameter를 마스킹합니다.

관리자 제어: 관리자 콘솔 관리 ➔ 개인정보 메뉴에서 차단 key와 URL Parameter를 변경할 수 있습니다. SDK는 자동 DOM text 수집을 기본 비활성화하고 흔한 이메일·전화번호·주민번호 형태의 Error Message를 치환하지만, Custom Property 값까지 판별하지는 않으므로 연동 단계에서도 PII를 보내지 않아야 합니다.

4. C클래스 / CIDR 서브넷 망대역 맵핑

사내 C-Class 및 CIDR IP 서브넷 대역을 특정 물리적 오피스 또는 사업장 이름으로 매핑합니다.

[
  { "cidr": "10.10.0.0/16", "name": "본사 판교 R&D 센터" },
  { "cidr": "10.20.0.0/16", "name": "서초 디지털 오피스" },
  { "cidr": "192.168.100.0/24", "name": "사내 SSL-VPN 접속망" }
]

5. API 키 관리 (Lifecycle) & 감사 로그 (Audit Trail)

5.1 API 키가 할 수 있는 일

개인 API 키(mom_key_)는 분석 데이터를 읽기 위한 것입니다. 스크립트나 BI 도구에서 사용합니다.

5.1.1 API 키 발급 및 회전 (Rotation)

5.2 감사 로그 (Audit Trail)

6. 사이트별 보존정책과 Dimension Registry

7. 사이트 Timezone과 참여 세션 기준

8. 개인정보 삭제 일관성

Visitor, User ID, 기간 또는 Site 삭제는 PostgreSQL Inbox와 Dead Letter 원본 payload를 먼저 정리하고 Raw Event를 삭제한 뒤 남은 Raw Event에서 Session, Visitor, Identity Graph와 일별 집계를 재생성합니다. User ID 삭제 시 Identity Graph에 연결된 로그인 전 익명 Visitor와 다른 기기의 Raw Event도 함께 삭제합니다. Event Property 삭제도 처리 대기/Debug payload와 Raw Event에 함께 적용됩니다. 따라서 삭제된 데이터가 Worker 재시도로 복원되거나 파생 보고서에 잔존하지 않습니다.

9. Identity Graph와 파생 집계 운영

10. Environment와 Event Contract

11. Semantic Metric과 Data Quality

12. Report / Action 보안

Scheduled Report를 사용하려면 먼저 관리자 설정 automation에서 기능을 활성화하고 allowed_webhook_hosts를 지정해야 합니다. 빈 Allowlist에서는 어떤 Endpoint도 호출하지 않습니다.

13. Analytics Engineering

14. Aggregate와 Late Event 운영

Event가 수신 시각보다 한 시간 이상 과거이면 Momento는 Site Timezone의 해당 날짜에 late_event 재집계 Job을 한 건만 생성합니다. Maintenance Worker는 Raw Event를 기준으로 Site/Visitor/Session 일별 집계를 다시 계산합니다. 관리자는 Analytics Engineering에서 367일 이하 Date Range 또는 Full Rebuild를 요청할 수 있습니다.

15. 값 기반 PII와 Privacy Request

16. Workspace와 Experiment 운영

17. 관리 센터 운영 UX