역할/권한 관리¶
본 챕터에서는 솔루션에서 사용하는 역할(Role) 및 권한(Permission) 의 정의와 사용자 할당 절차를 설명합니다.
SuperUser — 좌상단 관리 설정 모드에 접근할 수 있는 관리자 계정입니다. 부여된 역할 에 따라 사이드바에 노출되는 메뉴 범위(시스템 관리자·거버넌스 담당자 등) 가 달라집니다. SuperUser 지정은 사용자 관리 의 사용자 편집 모달에서 사용자 유형 을
Superuser로 설정해 수행합니다.
권한 모델 — 2단계 구조¶
XGEN 의 권한 체계는 역할(Role) 과 권한(Permission) 두 단계 구조로 구성됩니다.
| 레이어 | 답하는 질문 | 값의 형태 | 정의 주체 | 예시 | 어디서 효과 |
|---|---|---|---|---|---|
| 역할 (Role) | 어떤 관리 메뉴를 보는가? | 다중 라벨 배열 | 조직이 자유롭게 정의 | 시스템 관리자, 거버넌스 담당자, 분석가, 운영자 | 사이드바 노출 메뉴 범위 |
| 권한 (Permission) | 화면 안의 섹션·탭·버튼을 사용할 수 있는가? | ABAC 키 배열 | 권한 카탈로그 → 역할 또는 사용자에 매핑 | admin.user:read, main.agentflow:manage |
화면 내부의 섹션·탭·버튼 단위 게이팅 |
권한은 역할에 묶거나 개별 사용자에게 직접 부여 합니다. 보통 역할 단위로 묶고, 예외 케이스만 개별 권한 으로 보강하는 것을 권장합니다.
권한 확인 방식¶
사용자가 볼 수 있는 메뉴와 버튼은 시스템이 사용자 권한에 따라 자동으로 제어합니다. 권한 확인은 아래 순서로 진행됩니다.
1. 관리자(SuperUser) 여부 확인
먼저 사용자가 SuperUser 계정인지 확인합니다. SuperUser 계정은 기본적으로 모든 관리 기능에 접근할 수 있습니다.
단, 내부 운영 정책에 따라 시스템 관리자와 거버넌스 담당자의 관리 메뉴 권한은 일부 구분될 수 있습니다.
2. 사용자 권한 확인
SuperUser 가 아닌 경우에는 사용자에게 적용된 권한을 기준으로 접근 가능한 메뉴를 확인합니다. 이때 적용되는 권한은 사용자에게 직접 부여된 권한과, 사용자가 속한 역할(Role)에 묶인 권한을 모두 합친 합집합(Union) 입니다. 따라서 직접 권한 또는 역할 권한 중 어느 한쪽에만 해당 메뉴 접근 권한이 있어도 그 메뉴는 표시됩니다.
예를 들어 사용자 관리 메뉴 접근 권한(admin.user:read)이 사용자 본인에게 직접 부여돼 있지 않더라도, 그가 속한 역할 중 하나가 이 권한을 가지고 있으면 사용자 관리 메뉴가 표시됩니다. 반대로 역할에는 없지만 직접 권한으로 받은 경우에도 동일하게 표시됩니다.
예시:
- 사용자 관리 권한 보유 → 사용자 관리 메뉴 표시
- Agent 제작 권한 보유 → Agent 제작 메뉴 표시
- 지식 관리 권한 보유 → 지식 관리 메뉴 표시
합집합 부여 — 단, 직접 거부(Deny) 는 예외
메뉴·기능 접근은 위와 같이 직접 권한 + 역할 권한의 합집합 으로 부여됩니다. 다만 사용자 관리 의 직접 권한 영역에서 특정 권한을 명시적으로 거부(Deny) 한 경우에는, 역할로 받은 동일 권한보다 거부가 우선 적용되어 해당 기능이 숨겨집니다. 한 사용자에게만 일시적으로 권한을 차단할 때 사용합니다.
3. 권한이 없는 기능은 자동 숨김
필요한 권한이 없는 메뉴 및 버튼은 화면에 표시되지 않습니다. 즉, 사용자는 본인에게 허용된 기능만 확인할 수 있으며, 권한이 없는 기능은 자동으로 숨겨집니다.
사용자에게 권한을 부여하는 3가지 방법¶
| # | 부여 방법 | 어디서 부여하나 | 대표 사용 사례 |
|---|---|---|---|
| 1 | 역할 + 그 역할에 묶인 권한 | 본 챕터 → 역할 탭 → 역할 생성 → 권한 버튼 | "분석가" 역할로 main.knowledge:read 등 일관 권한 묶음 부여 |
| 2 | 역할 간 상속 (Supervision) | 본 챕터 → 권한 구조 탭 → 상위/하위 관계 추가 | "팀장 ← 팀원" 으로 팀장이 팀원 권한까지 자동 보유 |
| 3 | 개별 사용자에게 직접 부여 | 사용자 관리 → 사용자 편집 → 직접 권한 | 한 사용자에게만 일시적으로 권한 1개 Grant / Deny |
역할 탭¶
좌측 메뉴에서 관리 설정 > 사용자 / 접근제어 > 역할/권한 관리 를 선택하면 역할 탭이 기본 화면으로 표시됩니다.
상단 영역 — 탭·검색·액션 버튼¶
| 영역 | 위치 | 설명 |
|---|---|---|
| 탭 — 역할 | 좌측 상단 (기본 탭) | 등록된 역할(Role) 목록을 확인합니다. |
| 탭 — 권한 구조 | 좌측 상단 두 번째 | 역할 간 상속 관계(Supervision)를 관리합니다 — 권한 구조 탭 |
| 검색 | 우측 상단 검색창 | 역할명 또는 표시명을 기준으로 역할을 검색합니다. |
| 버튼 — 권한 조회 | 우측 상단 | 특정 사용자의 최종 적용 권한을 조회합니다 — 권한 조회 모달 |
| 버튼 — 역할 생성 | 우측 상단 | 신규 역할(Role)을 생성합니다 — 역할 생성 |
| 버튼 — 새로고침 | 우측 상단 | 역할 목록을 최신 상태로 다시 조회합니다. |
역할 테이블¶
역할 목록 테이블에서는 등록된 역할 정보와 관리 기능을 확인할 수 있습니다. 정렬 아이콘(↓)이 표시된 컬럼은 클릭하여 오름차순/내림차순으로 정렬할 수 있습니다.
| 컬럼 | 설명 |
|---|---|
| 역할명(영문) | 시스템 내부에서 사용하는 역할 식별자입니다. kebab-case 형식을 권장합니다. 예: analyst, content-manager. 역할명은 시스템 식별 키로 사용되므로 생성 후 변경하지 않는 것을 권장합니다. |
| 표시명 | 화면에 표시되는 역할 이름입니다. 예: 분석가, 콘텐츠 관리자 |
| 권한 수 | 해당 역할에 연결된 권한(Permission) 개수입니다. 0인 경우 아직 권한이 할당되지 않은 상태입니다. |
| 설명 | 역할에 대한 간단한 설명입니다. 설명이 없는 경우 - 로 표시됩니다. |
| 작업 | 역할별 관리 기능 버튼입니다. 사용자 관리, 권한 설정, 편집, 삭제 기능을 제공합니다. |
각 역할 행의 작업 버튼을 통해 사용자 할당, 권한 설정, 역할 수정 등의 관리 작업을 수행할 수 있습니다.
| 버튼 | 설명 |
|---|---|
| 사용자 | 해당 역할이 할당된 사용자 목록을 확인합니다. 상단의 할당된 사용자 영역에서는 × 버튼으로 역할을 즉시 회수할 수 있으며, 하단의 사용 가능한 사용자 목록에서는 + 추가 버튼을 통해 여러 사용자에게 역할을 할당할 수 있습니다 — 할당된 사용자 모달 |
| 권한 | 역할에 연결할 권한(Permission)을 설정합니다. 권한은 ADMIN, MAIN 등 권한 범주별로 구분되어 표시됩니다 — 권한 설정 모달 |
| 편집 | 역할명(영문), 표시명, 설명 정보를 수정합니다. 역할명은 시스템 식별자로 사용되므로 생성 이후 변경하지 않는 것을 권장합니다. |
| 삭제 | 역할을 삭제합니다. 해당 역할이 사용자에게 할당되어 있는 경우에는 삭제할 수 없으며, 경고 메시지가 표시됩니다. |
역할 생성¶
역할 생성은 두 단계 입니다 — 먼저 역할명을 등록하고, 그 다음 역할 행의 권한 버튼으로 권한 체크리스트를 부여합니다.
1단계 — 역할 등록¶
- 역할 목록 우상단 역할 생성 클릭
- 모달에서 다음 항목 입력:
- 역할명 (영문) — 예:
content-manager(중복 불가) - 표시명 — 예:
콘텐츠 관리자 - 설명 — (선택)
- 역할명 (영문) — 예:
- 모든 필수 항목이 채워지면 우하단 생성 버튼이 활성화 — 클릭하면 역할이 권한 0개로 등록됩니다.
2단계 — 권한 부여¶
생성된 역할에 권한을 부여하려면 역할 목록 테이블에서 해당 행의 권한 버튼을 클릭합니다. 권한 설정 모달이 열리고 두 스코프(ADMIN / MAIN) 의 권한이 카테고리별로 펼쳐집니다.
권한 설정 화면 구성¶
권한 설정 화면에서는 역할(Role)에 연결할 권한(Permission)을 선택하고 관리할 수 있습니다.
| 영역 | 설명 |
|---|---|
| 헤더 | 현재 편집 중인 역할명이 표시됩니다. 예: 권한 설정: 콘텐츠 관리자 |
| 검색창 | 권한명 또는 키워드를 검색하여 필요한 권한을 빠르게 찾을 수 있습니다. |
| 스코프 카운트 배지 | ADMIN, MAIN 등 권한 범주별 선택 현황을 표시합니다. 예: ADMIN 76/76, MAIN 33/33. 전체 선택 개수도 함께 표시됩니다. |
| 권한 체크 트리 | 권한은 스코프 및 카테고리 단위로 그룹화되어 표시됩니다. 화살표(▶)를 클릭하여 하위 권한 목록을 펼칠 수 있으며, 카테고리 체크박스를 선택하면 해당 그룹의 권한을 한 번에 선택 또는 해제할 수 있습니다. |
| 선택 상태 표시 | 화면 하단에 현재 선택된 권한 수가 실시간으로 표시됩니다. 예: 109개 선택됨 |
| 버튼 — 취소 / 저장 | 변경 사항은 저장 버튼을 눌러야 최종 반영됩니다. 저장 완료 후 역할 목록의 권한 수 정보가 함께 갱신됩니다. |
사용자 할당 — 권한 부여 후¶
권한이 설정된 역할은 행 우측 사용자 버튼으로 사용자에게 일괄 할당합니다.
사용자 할당 화면 구성¶
사용자 할당 화면에서는 특정 역할(Role)에 연결된 사용자를 조회하고 추가 또는 회수할 수 있습니다.
| 영역 | 설명 |
|---|---|
| 할당된 사용자 | 현재 해당 역할이 부여된 사용자 목록이 칩(Chip) 형태로 표시됩니다. 각 사용자 칩의 × 버튼을 선택하면 역할이 즉시 회수됩니다. |
| 사용 가능한 사용자 | 역할을 추가로 부여할 수 있는 사용자 목록입니다. 검색창을 통해 사용자를 필터링할 수 있으며, 사용자 우측의 + 추가 버튼을 선택하면 역할이 할당됩니다. 여러 사용자에게 동시에 역할을 부여할 수 있습니다. |
| 닫기 | 사용자 할당 화면을 종료합니다. 추가 및 회수 작업은 즉시 반영됩니다. |
여러 역할을 사용자에게 할당하는 경우¶
역할 화면의 사용자 버튼은 여러 사용자에게 동일한 역할을 일괄 할당할 때 적합합니다.
반대로, 한 사용자에게 여러 역할을 동시에 부여해야 하는 경우에는 사용자 관리 화면의 사용자 편집 모달에서 역할을 설정하는 방식을 권장합니다.
예시:
- 사용자 관리 > 사용자 편집 > 권한 탭
- 여러 역할(Role) 선택 후 저장
이 방식은 사용자 기준으로 권한 구성을 관리할 때 더욱 효율적입니다.
자주 쓰는 시나리오¶
케이스 1 — 신규 직무에 맞는 역할 신설 ("컴플라이언스 담당" 예시)
- 역할 탭 → 역할 생성
- 모달 입력: 역할명
compliance-officer/ 표시명컴플라이언스 담당/ 설명 "AI 사용 위험 검토, 감사 로그 정기 조회" - 행 우측 권한 버튼 →
admin.governance:*+admin.audit:read+admin.user:read체크 → 저장 - 행 우측 사용자 버튼 → 컴플라이언스팀 구성원 다중 선택 → 일괄 할당
케이스 2 — 팀 단위 권한 묶음 ("EC 개발팀" 예시)
- 역할 탭에서 기존 EC Development Team 1 행의 권한 버튼 → 묶음 확인
- 신규 팀원이 입사하면 같은 행의 사용자 버튼 → 추가만 하면 권한 자동 부여
- 팀에 새 책임이 추가되면 권한 버튼으로 해당 권한 체크 → 같은 팀 전체에 즉시 반영
케이스 3 — 일회성·임시 권한 (한 사용자만 일시적으로)
- 본 화면이 아닌 사용자 관리 의 사용자 편집 모달 → 직접 권한 영역에서 Grant / Deny
- 임시 권한을 역할 로 만들면 다른 사용자에게도 영향 — 1명에만 적용할 때는 직접 권한 이 안전합니다
권한 구조 탭 — 상위/하위 권한¶
복잡한 조직에서는 역할 간 상하 관계(Supervision) 를 정의해 상위 역할이 하위 역할 권한까지 자동 상속 받게 할 수 있습니다.
- 상위 권한 (Supervisor Role): 더 큰 권한 집합을 가진 역할
- 하위 권한 (Target Role): 더 작은 권한 집합을 가진 역할
예: "팀장" 역할이 "팀원" 역할을 상속하면, 팀장에게는 팀원 권한 + 팀장 고유 권한 이 모두 적용됩니다. 팀원 권한이 추가·변경되면 팀장도 자동으로 같은 변경을 받습니다.
화면 구성¶
상단 권한 구조 탭을 클릭하면 등록된 상하 관계가 표 형태로 노출됩니다.
| 영역 | 설명 |
|---|---|
| 상단 카운트 | 좌측에 총 N개, 표시 N개, 페이지 1/N — 등록된 관계 총합과 현재 페이지. |
| 검색창 | 상위/하위 권한 또는 설명으로 검색... — 행을 즉시 필터링. |
| 버튼 — 권한 조회 | 역할 탭과 동일한 사용자 권한 조회 모달을 엽니다 (권한 조회 모달). |
| 버튼 — 권한 구조 추가 | 보라색. 새 상하 관계 등록 모달 — 상위 권한 1개 + 하위 권한 N개 + 설명(선택) 입력. |
| 버튼 — 새로고침 | 목록 즉시 재조회. |
테이블 컬럼:
| 컬럼 | 설명 |
|---|---|
| 체크박스 | 다중 선택 — 일괄 삭제 등 향후 작업용. |
| 상위 권한 ↓ | 더 큰 권한 집합을 가진 역할 (영문 식별자). |
| 하위 권한 ↓ | 상속받는 역할 (영문 식별자). 같은 상위 권한이 여러 하위를 가지면 행이 별도로 노출. |
| 설명 | 관계의 의미 (없으면 -). |
| 작업 | 행 우측 삭제 (빨간 테두리) — 클릭 시 해당 상하 관계 즉시 해제. |
작업 흐름 — 상하 관계 등록¶
- 권한 구조 탭의 우상단 권한 구조 추가 클릭.
- 모달에서 다음 항목 선택:
- 상위 권한 — 더 큰 권한을 가진 역할 1개 (드롭다운).
- 하위 권한 — 상속받는 역할(들) — 다중 선택 가능.
- 설명 — 선택 입력.
- 저장 클릭. 목록에 즉시 새 행이 노출됩니다.
상위 역할에 할당된 사용자는 즉시 하위 권한까지 보유한 상태가 됩니다 — 재로그인이나 새로고침 불필요 (다만 본인 사이드바 갱신은 다음 페이지 이동 시 반영).
작업 흐름 — 상하 관계 해제¶
행 우측 삭제 버튼을 클릭하면 즉시 해당 상하 관계가 해제됩니다. 상위·하위 역할 자체 는 삭제되지 않으며 상속 관계만 끊어집니다. 끊긴 즉시 상위 역할 사용자의 권한 합성에서 해당 하위 권한이 빠집니다.
권한 조회 — 특정 사용자에게 최종 적용된 권한 목록을 확인하는 기능¶
역할 탭 또는 권한 구조 탭 우상단의 권한 조회 버튼은 한 사용자가 최종적으로 보유한 권한 을 한 화면에서 확인하는 데 사용합니다. 역할·상속·직접 권한이 모두 합쳐진 결과를 보여 주므로 "왜 이 메뉴가 안 보일까" 또는 "의도치 않게 광범위 권한이 부여돼 있는 건 아닐까" 같은 추적·감사에 유용합니다.
화면 구성:
- 사용자 검색 입력칸에 이메일·이름·사용자명 일부 입력.
- 일치하는 사용자 목록에서 1명 선택.
- 하단 권한 조회 버튼 클릭 → 합성된 권한이 펼쳐집니다.
권한 조회 버튼이 안 보이면
권한 조회 는 별도 권한(admin.permission:*) 을 가진 SuperUser 에게만 노출됩니다. 본인이 해당 권한 보유자인지 역할/권한 관리 → 본인 행의 권한 버튼으로 확인할 수 있습니다.
사용자에게 역할 할당¶
방법 A — 역할 화면에서 (다수 사용자에게 한 번에)
- 역할 목록에서 대상 역할의 사용자 버튼 클릭 → 사용자 관리 모달이 열립니다.
- 하단 사용 가능한 사용자 목록에서 검색·선택 후 + 추가 — 다중 할당 가능.
- 변경 사항은 즉시 반영되며 닫기 로 종료합니다.
방법 B — 사용자 화면에서 (한 사용자에게 여러 역할)
- 사용자 관리 → 사용자 편집 모달 → 권한 탭으로 전환.
- 역할 영역에서 여러 역할을 선택합니다 (다중 선택 가능).
- 저장 클릭.
권한 회수¶
| 작업 | 절차 |
|---|---|
| 역할에서 사용자 빼기 | 역할 상세 → 할당된 사용자 → 해당 사용자 옆 × 제거 |
| 역할 자체 삭제 | 역할 목록에서 삭제 — 단, 이 역할에 할당된 사용자가 있으면 차단됨 |
역할 삭제 전 확인
삭제 전 할당된 사용자 수를 확인하세요. 0이 아니면 먼저 사용자에서 해당 역할을 회수해야 합니다.
운영 권장사항¶
역할 명명 (생성 단계)
- 영문 식별자(
name)는 kebab-case (예:content-manager) — DB 키로 영구 보존되므로 일관성이 중요합니다. - 표시명(
display_name)은 조직의 직무·부서명 과 일치시키면 사용자 관리·감사 시 직관적입니다. - 설명은 한 줄로 — "무엇을 하는 역할인가" 가 인수인계·검색 시 결정적입니다.
권한 부여 (역할 운영)
- 최소 권한 원칙 — 시작은 좁게, 필요할 때 추가. 광범위한 권한(예:
*:*) 은 SuperUser 외에는 부여하지 않습니다. - 임시 권한은 별도 역할로 — 변동성이 큰 임시 권한은 임시 역할 에 모아 회수 시 일괄 처리. 사용자 직접 권한 은 1명에만 적용할 때만 사용합니다.
- Direct deny 는 예외용 — 역할로 받은 권한 중 특정 사용자만 차단해야 할 때만. 자주 쓰면 권한 흐름이 추적 불가합니다.
정기 점검 (분기 1회 권장)
- 할당 사용자 0명 역할 — 의도된 컨테이너 인지, 정리 누락인지 검토 후 삭제 또는 안내
- 권한 0개 역할 — 같은 기준으로 검토
- Supervision 그래프 — 불필요한 상속 관계 제거. 깊이 3 이상이면 직접 권한 부여 가 더 단순한지 재검토
자주 발생하는 문제¶
| 증상 | 원인 / 점검 |
|---|---|
| "권한이 있는데 사이드바 메뉴가 안 보여요" | 사이드바 가시성은 권한 prefix 매칭 기준. 예: admin.user:read 만 있으면 사용자 관리 사이드바는 보이고 AI 거버넌스 사이드바는 안 보임. |
| "역할은 부여했는데 메뉴가 안 열려요" | 사용자가 재로그인 또는 토큰 갱신 필요. 또는 SuperUser 권한이 필요한 메뉴(예: 관리 설정 모드 전체) 일 수 있음 — 사용자 관리 에서 사용자 유형 을 Superuser 로 변경. |
| "역할 삭제 시 'X명이 할당되어 있어 삭제할 수 없습니다'" | 의도된 안전장치. 역할 행의 사용자 버튼으로 진입해 사용자 0명으로 만든 뒤 다시 시도. |
| "한 사용자만 임시로 권한 끄고 싶어요" | 사용자 관리 → 편집 → 직접 권한 영역에서 해당 권한을 Deny 로 설정. 역할 → grant 와 직접 → deny 가 있으면 deny 가 우선 적용됩니다. |
| "권한 조회 버튼이 안 보여요" | 권한 조회 는 별도 권한(admin.permission:*) 보유자에게만 노출됩니다. 본인 권한에 포함됐는지 확인. |
문의¶
역할/권한 관련 문의는 Xgen 솔루션 관리자에게 문의해 주세요.