역할 관리 및 데이터 접근제어
GenD 플랫폼의 역할 기반 접근 제어(RBAC)와 Unity Catalog 패턴 데이터 접근제어 체계입니다.
역할 계층
GenD는 3단계 역할 계층과 인가 함수를 사용합니다:
admin ────── 모든 기능 + 모든 데이터
│
analyst ──── 쿼리 실행 + 할당된 카탈로그
│
viewer ───── 읽기 전용 + 할당된 카탈로그
인가 함수
| 함수 | 허용 역할 | 사용 위치 |
|---|---|---|
require_admin(user) | admin | 보안, 정책, 사용자관리, 감사 등 |
require_analyst(user) | admin, analyst | 쿼리 실행, 저장 쿼리 생성, 수집 업로드 등 |
require_viewer(user) | admin, analyst, viewer | 카탈로그 조회, 대시보드, 목록 조회 등 |
기능별 권한 매트릭스
| 기능 | admin | analyst | viewer |
|---|---|---|---|
| SQL 에디터 | 모든 쿼리 | SELECT + INSERT | SELECT only |
| 카탈로그 탐색 | 전체 | 할당된 카탈로그 | 할당된 카탈로그 |
| 저장 쿼리 | CRUD | 생성/조회/수정 | 조회만 |
| AI/NL2SQL | 전체 | 사용 가능 | 사용 가능 |
커넥터 관리 (전사 /connectors) | CRUD | 조회만 | 조회만 |
| 데이터 마트 | CRUD | 조회만 | 조회만 |
파이프라인 실행 이력 (/pipeline) | CRUD | 조회만 | 조회만 |
파이프라인 스튜디오 (/pipeline-studio) | CRUD | 작성·배포·실행 | 조회만 |
| 수집 (Ingestion) — 파일 업로드 | CRUD | 업로드/조회 | 조회만 |
| 수집 소스(공용 수집기) | CRUD | 접근 불가 | 접근 불가 |
| 수집 정책·외부 파서 | CRUD | 조회만 | 조회만 |
| 타임트래블 (스냅샷 조회) | 전체 | 조회 (grant 필요) | 조회 (grant 필요) |
| 타임트래블 (시점 데이터 조회) | 전체 | 조회 (grant + 마스크 정책 없음) | 접근 불가 |
| 리니지 (그래프·영향도·테이블 목록) | 전체 | 조회 (grant 필요, 이웃 노드도 필터) | 동일 |
| PII 관리 | CRUD | 조회만 | 접근 불가 |
| 감사 로그 | 전체 | 접근 불가 | 접근 불가 |
| 사용자 관리 | CRUD | 접근 불가 | 접근 불가 |
| Data Grant 관리 | CRUD | 접근 불가 | 접근 불가 |
위 표의 "데이터 마트 analyst 생성/조회" 와 "파이프라인 analyst 조회만" 은 코드와
어긋나 있었습니다. 실제로는 데이터 마트 생성/갱신이 require_admin 이고, 파이프라인
스튜디오는 require_analyst 로 작성·배포·실행까지 가능합니다. 같은 날 타임트래블·
리니지 조회에 인가가 배선되어 행이 추가됐습니다 —
쿼리 실행 DataGrant 시행
참조.
워크스페이스 관리자 (ws-admin) — 독립 축
realm 역할과 별개로 Keycloak /tenants/{slug}/admins 그룹 소속 여부가
TokenPayload.is_workspace_admin(slug) 를 결정합니다 (글로벌 admin 은 모든
워크스페이스에서 암묵 충족). 담당 범위는
워크스페이스 관리자 가이드 를 보세요.
부여 경로는 멤버 추가 API 의 dept 필드에 admins 를 넣는 것뿐입니다
(POST /api/v1/workspaces/{id}/members → {"user_id": …, "dept": "admins"}).
POST /api/v1/workspaces 는 clearance 하위 그룹만 만들고 admins 는 만들지
않으며, /admin/users 화면의 그룹 설정은 최상위 그룹만 다뤄 서브그룹을 지정할 수
없습니다. 전용 UI 가 없다는 뜻이므로 운영 시 주의하세요.
LLM 보안 등급 (독립 축)
| 등급 | Keycloak 역할 | 접근 데이터 |
|---|---|---|
| TOP_SECRET | gend-llm-internal | 모든 데이터 |
| CONFIDENTIAL | gend-llm-confidential | 기밀 이하 |
| PUBLIC | gend-llm-external (기본) | 공개 데이터만 |
데이터 접근제어 (DataGrant)
Databricks Unity Catalog 패턴의 deny-by-default 데이터 접근제어입니다.
deny-by-default 원칙
- 명시적 GRANT가 없으면 카탈로그/스키마/테이블이 보이지 않음
- Admin은 항상 전체 접근 (bypass)
- catalog GRANT → 하위 모든 schema/table 접근 가능
Privilege 유형
| Privilege | 의미 | 적용 대상 |
|---|---|---|
USE | 존재 확인 + 탐색 | catalog, schema |
SELECT | 데이터 조회 | table (상위 적용 시 하위 전체) |
INSERT | 데이터 삽입 | table |
ALL | 모든 권한 | catalog, schema, table |
Grantee 유형
| 유형 | 예시 | 설명 |
|---|---|---|
role | analyst, viewer | Keycloak 역할 기반 |
group | marketing, finance | Keycloak 그룹 (부서) 기반 |
user | user-id-123 | 특정 사용자 직접 부여 |
GRANT 예시
# analyst 역할에 iceberg 카탈로그 SELECT 권한
curl -X POST /api/v1/data-grants \
-d '{"grantee_type":"role","grantee_name":"analyst","object_type":"catalog","catalog_name":"iceberg","privilege":"SELECT"}'
# marketing 그룹에 hive 카탈로그 전체 권한
curl -X POST /api/v1/data-grants \
-d '{"grantee_type":"group","grantee_name":"marketing","object_type":"catalog","catalog_name":"hive","privilege":"ALL"}'
Trino SQL 권한
DataGrant 레코드는 자동으로 Trino rules.json으로 변환됩니다. 기본 정적 규칙:
| 역할 | iceberg | nessie | tpch/tpcds | sourcedb | system |
|---|---|---|---|---|---|
| admin | all | all | all | all | all |
| analyst | read-only | read-only | read-only | - | read-only |
| viewer | read-only | - | read-only | - | none |
Trino 리소스 제한
역할별 쿼리 리소스 그룹(resource-groups.json):
| 역할 | 메모리 한도 | 동시 쿼리 | 대기열 |
|---|---|---|---|
| admin | 50% | 20 | 100 |
| analyst | 30% | 10 | 50 |
| viewer | 15% | 5 | 20 |
사용자 관리
관리자는 GenD UI에서 직접 사용자 역할/그룹을 관리합니다 (Keycloak Admin Console 접근 불필요).
자세한 내용은 사용자 관리 가이드를 참조하세요.
ABAC (속성 기반 접근 제어)
RBAC 외에 ABAC(속성 기반)으로 세분화된 정책을 적용합니다. 사용자 속성(부서, 등급)과 데이터 속성(민감도, 분류)을 조합하여 접근을 제어하며, 행/열 수준 정책은 QueryPolicyEnforcer(row_filter/column_mask), 카탈로그 가시성은 DataAccessService, 벡터 RAG 문서 접근은 vector_policy_enforcer가 각각 active 워크스페이스 기준으로 강제합니다.
관련 문서
관리자 데이터 열람 — break-glass (#2700 D2)
플랫폼 관리자(admin)의 권한을 관리 기능과 데이터 열람으로 나눈다.
| 영역 | 예시 | 필요 자격 |
|---|---|---|
| 관리 기능 | 워크스페이스·권한 생성/수정, 감사 로그 조회, 테이블 쓰기 권한 검사 | admin (그대로) |
| 데이터 열람 | 카탈로그·스키마·테이블 목록, 행 조회, 쿼리 결과 | admin + ws_break_glass |
| 데이터 변경 (#2798) | 워크스페이스 귀속 자산의 수정·삭제·갱신 (데이터마트, 수집 파일·정책, 파이프라인 취소) | admin + ws_break_glass, 또는 해당 워크스페이스 활성 컨텍스트 |
데이터 변경은 열람과 같은 모드 스위치를 탄다. 2026-08-03 까지는 열람만 좁혀져
있어 ws_break_glass 없는 관리자도 타 워크스페이스 자산을 ID 로 수정·삭제할 수
있는 비대칭이 있었다 — #2798 슬라이스 1 이 쓰기 평면을 같은 규칙으로 맞췄다.
전환 실측(감사 인덱스 30일): 해당 경로 실사용 107건 전부가 break-glass 보유
계정이라 영향 0.
조사한 11개 데이터 플랫폼 중 관리자에게 데이터 평면까지 전면 허용하는 것은 GenD 뿐이었다. 다수는 관리 평면만 우회한다.
판정 규칙
ws_break_glass 역할 멤버십으로만 판정한다. admin 이라는 이유로 자동 부여되지
않는다.
:::warning 이 분리가 무너진 전례가 있다
과거 PII 마스킹 면제에서 admin 이면 자동으로 참이 되게 만들었다가, "관리자면 원본을
본다"가 기본 동작이 되어 통제가 무력해졌다(#2673). 같은 실수를 막기 위해 역할
멤버십만 본다.
:::
모드
GEND_ADMIN_DATA_PLANE_MODE
| 값 | 동작 |
|---|---|
observe (기본) | 현행 유지 + 관측만 — 배포로 아무것도 막히지 않는다 |
enforce | 역할 없는 관리자는 다른 워크스페이스 데이터를 볼 수 없다 |
off | 관측도 하지 않음 (롤백) |
알 수 없는 값은 enforce 로 폴백한다.
enforce 전환 절차
★ 순서를 지켜야 한다 — 틀리면 운영자 전원이 동시에 잠긴다. 운영 클러스터는 수동 배포라 자동 롤백이 없다.
observe로 배포gend_admin_data_plane_bypass_total{mode="observe"}를 최소 1주 관측- Keycloak 에서
ws_break_glass역할을 먼저 부여 (필요 운영자 전원) - 부여를 확인한 뒤
GEND_ADMIN_DATA_PLANE_MODE=enforce
:::caution 형해화 주의 2단계 분포가 매일 오르면 사유 입력이 형식이 된다. 그 경우 전환보다 왜 매일 필요한가를 먼저 봐야 한다 — 대개 운영 절차가 관리자 계정에 과도하게 의존한다는 신호다. :::
알람
increase(gend_admin_data_plane_bypass_total{mode="enforce"}[1h]) > 0
enforce 에서 이 값이 오르면 역할 없는 관리자가 막히고 있다 — 3단계(역할 선부여)가
누락됐는지 확인한다.
대외 문구
- ✅ "관리자의 데이터 열람은 별도 역할과 사유 입력을 요구하며, 그 행위가 기록됩니다"
- ⛔ "관리자도 열람할 수 없습니다" — Keycloak 관리자는 자기에게 역할을 부여할 수 있다
워크스페이스 관리자의 멤버십 관리 (#2743)
워크스페이스 관리자(ws-admin)가 자기 워크스페이스의 멤버를 직접 추가·제거·조회한다. 이전에는 팀 구성원이 바뀔 때마다 플랫폼 관리자에게 요청해야 했다.
위임 범위 — 멤버십만
| 기능 | 위임 |
|---|---|
| 멤버 목록 조회 | ✅ ws-admin |
| 멤버 추가 | ✅ ws-admin |
| 멤버 제거 | ✅ ws-admin |
| 역할 변경(viewer↔analyst↔admin) | ⛔ 플랫폼 관리자 |
:::warning 역할 변경을 위임하지 않는 이유
GenD 의 viewer/analyst/admin 은 워크스페이스가 아니라 전사 범위 역할이다.
ws-admin 에게 위임하면 자신을 admin 이나 unmask 로 승격하는 경로가 열린다.
워크스페이스 범위 역할 모델을 새로 만드는 방법도 있으나, 운영 환경 실측상 여러 워크스페이스에 동시 소속된 사용자가 3명뿐이라 그 비용이 정당화되지 않았다. :::
자기 워크스페이스만
ws-admin 은 자신이 관리자인 워크스페이스만 다룰 수 있다. 다른 워크스페이스의 멤버를 조회·변경하려 하면 403 이다.
활성화
GEND_WS_ADMIN_MEMBERSHIP_ENABLED=true
:::caution 기본값이 꺼져 있다 — 다른 플래그와 방향이 반대다
격리 관련 플래그들은 권한을 좁히므로 관측 모드로 시작해도 안전하다. 이 기능은
권한을 넓히므로 기본값이 false 이고, 명시적으로 켜야 한다.
켜기 전에 각 워크스페이스의 ws-admin 명부(/tenants/<slug>/admins 그룹)를 확인하라.
:::