관리자 역할 및 권한 (RBAC)
대상: 슈퍼 관리자 대시보드의 일부를 위임해야 하지만 전체 슈퍼 관리자 권한을 넘기고 싶지 않은 플랫폼 소유자 및 슈퍼 관리자.
이 기능이란
과거에는 AAEKB의 슈퍼 관리자 접근이 전부 아니면 전무였습니다. 계정은 전체 슈퍼 관리자(모든 탭, 모든 동작, 플랫폼 전체)이거나 좁은 Monitoring 플래그(읽기 전용 Logs & Auditing)를 가질 뿐, 그 사이는 없었습니다.
슈퍼 관리자 RBAC는 이 이진 구조를 **관리자 역할(admin role)**로 대체합니다. 관리자 역할은 슈퍼 관리자 대시보드의 표면 전반에 걸친 이름이 지정된 권한 번들입니다. 사용자에게 관리자 역할을 정확히 하나 할당하면, 그 역할이 다음을 결정합니다:
- 사용자에게 표시될 슈퍼 관리자 사이드바의 탭
- 각 탭이 완전히 상호작용 가능한지 읽기 전용인지
- Super Admin 항목이 최상위 탐색에 아예 표시되는지
네 개의 역할이 기본 제공되며, 필요한 만큼 사용자 정의 역할을 정의할 수 있습니다. 관리자 역할이 없는 사용자는 일반 AAEKB 사용자입니다: Super Admin 항목도 대시보드도 없습니다.
이것은 플랫폼 전체 관리이며 팀 또는 프로젝트 권한이 아닙니다. 팀 역할(Owner / Admin / Editor / Member)과 프로젝트 역할은 별개의 무관한 시스템입니다. 관리자 역할은 슈퍼 관리자 대시보드만 관장합니다.
전제 조건
- 관리자 역할 탭을 열려면 Admin Roles → View가, 그 안의 무엇이든 변경하려면 Admin Roles → Manage가 필요합니다. 전체 슈퍼 관리자는 기본적으로 둘 다 가집니다.
- 직접 링크:
/admin/super?tabName=roles(별칭?tabName=admin_roles도 작동).
구성 전에 알아야 할 개념
리소스와 동작
권한은 한 쌍입니다: 리소스(Users 또는 Teams 같은 슈퍼 관리자 표면)와 그 위에서 수행할 수 있는 동작(action).
| 동작 | 매트릭스 열 | 의미 |
|---|---|---|
view | View | 표면을 읽습니다. 탭 열기, 탐색, 검색, 필터, 세부 패널 열기. |
manage | Manage | 표면에 대한 완전한 생성 / 수정 / 삭제. 아래의 모든 것을 함의합니다. |
user_manage | User mgmt | 멤버만 관리 — 추가, 제거, 역할 변경, 소유자 재할당. Manage의 부분 집합으로, Teams와 Projects에서 사용 가능. |
export | Export | 표면의 데이터를 CSV/XLSX로 다운로드. Logs & Auditing에서 사용 가능. |
모든 동작이 모든 리소스에 적용되지는 않습니다. 역할 빌더에서 적용되지 않는 조합은 체크박스 대신 대시(—)로 표시됩니다.
동작 계층 구조
확인은 문자적이지 않습니다 — 일부 동작이 다른 동작을 충족시킵니다:
| 확인 대상 | 통과 조건 |
|---|---|
view | 해당 리소스에 대한 어떤 동작 (Manage만 체크해도 View를 함의) |
manage | manage |
user_manage | user_manage 또는 manage |
export | export 또는 manage |
실질적 결과: Manage를 체크하면 항상 충분합니다. 옆에 View를 체크할 필요는 없습니다. View를 따로 체크하는 것은 진정한 읽기 전용 권한을 주고 싶을 때만 하세요.
사용자에 대한 접근 해석 방식
할당된 역할이 기준입니다. 레거시 슈퍼 관리자 / 모니터링 플래그는 이 기능 이전에 존재했던 계정을 위한 하위 호환 폴백으로만 유지되며, 내장 Super Admin 또는 Monitoring 역할을 할당할 때마다 자동으로 동기화됩니다.
네 개의 내장 역할
이들은 자동으로 시드되며 역할 테이블에 System으로 표시됩니다. 권한은 고정되어 편집하거나 삭제할 수 없지만 — 조직이 다른 용어를 사용한다면 이름과 설명은 변경할 수 있습니다. 이들 중 하나의 변형이 필요하면 대신 사용자 정의 역할을 만드세요.
| 역할 | 권한 | 보유자가 얻는 것 |
|---|---|---|
| Super Admin | 모든 접근 | 모든 것. 레거시 슈퍼 관리자 플래그와 동일. |
| Monitoring | Logs & Auditing → View | Logs & Auditing만, 읽기 전용, 내보내기 없음. 레거시 모니터링 플래그와 동일. |
| Project Manager | Projects → View, Manage, User mgmt | 완전히 상호작용 가능한 Projects 탭: 생성, 편집, 복제, 이전, 프로젝트 구성원 및 역할 관리. |
| User Access Manager (UAM) | Access Controls → View, Manage; Users → View, Manage; Teams → User mgmt; Projects → User mgmt | Users와 Access Controls는 완전 상호작용; Teams는 읽기 전용으로 표시. 아래 참고 사항 참조. |
UAM 역할에 관한 참고. Teams와 Projects에 대한 user_manage 권한은 API가 존중하지만, 대시보드의 탭 표시 규칙 때문에 Projects 탭은 나타나지 않으며(Manage 필요), Teams 탭은 읽기 전용으로 열립니다(멤버 관리 컨트롤이 숨겨짐). 따라서 UAM 사용자는 Teams나 Projects가 아니라 Users 탭과 Access Controls를 통해 사용자를 관리합니다. Teams 탭에서 팀 구성을 진정으로 관리할 수 있는 역할이 필요하면 Teams → Manage가 있는 사용자 정의 역할을 만드세요.
권한 레퍼런스
역할 빌더에 표시되는 대로의 전체 매트릭스입니다.
처음부터 끝까지 작동하는 권한
대시보드와 API 모두 일관되게 강제합니다. 위임 역할을 구축할 때 이것들을 사용하세요.
| 리소스 | 동작 | 잠금 해제되는 탭 | 나타나는 조건 | 부여하는 것 |
|---|---|---|---|---|
| Users | View, Manage | Users | View | View: 모든 사용자 탐색 및 검색, 팀 정보와 SAML 메타데이터 열기, 로그인 IP 보기. Manage: 사용자 세부 정보 편집, 사용자 삭제, 사용자 생성, 비활성 재활성화 요청 승인/거부, 사용자 목록 내보내기. (내보내기 API는 View만 필요하지만 탭이 읽기 전용인 동안 버튼이 숨겨지므로, 이를 드러내는 것은 Manage입니다.) |
| Teams | View, Manage, User mgmt | Teams | View | View: 팀, 세부 정보, 멤버, 설정, 결제 및 팀 로그 탐색. Manage: 팀·서브도메인·설정 생성/편집/삭제, 라이선스 갱신, 소유권 이전. User mgmt: 팀 멤버 추가·제거·역할 변경 (API 수준; 위의 UAM 참고 사항 참조). |
| Projects | View, Manage, User mgmt | Projects | Manage | View: 모든 프로젝트 탐색·검색·검사. Manage: 프로젝트 복제, 팀 간 이전. User mgmt: 프로젝트 멤버 추가/제거, 멤버 역할 변경, 프로젝트 소유자 변경. |
| Access Controls | View, Manage | Access Controls | View | View: 현재 로그인 접근 모드, "Require pre-authorized account" 설정, 모든 SAML 접근 규칙 보기. Manage: 접근 모드 전환, 사전 승인 잠금 토글, SAML 접근 규칙 생성/편집/삭제. |
| Logs & Auditing | View, Export | Logs & Auditing | View | View: 모든 감사 표면 읽기 — 채팅, 사용자, 접근, 도구, 보안, 팀, SSO, 설정, 에이전트 템플릿 및 슈퍼 관리자 동작 로그. Export: 내보내기 버튼의 숨김 해제 — 단, 감사 로그 내보내기는 위임할 수 없습니다를 보세요. 내보내기 엔드포인트 자체는 여전히 전체 슈퍼 관리자에게만 제한됩니다. |
| Admin Roles | View, Manage | Admin Roles | View | View: 모든 역할과 그 권한 보기; Users 탭의 관리자 역할 피커를 사용할 수 있게 하는 데도 필요. Manage: 사용자 정의 역할 생성·편집·삭제, 어떤 사용자의 관리자 역할이든 변경. |
| Custom Toolkits | View, Manage | (탭 없음 — 현재 숨김) | — | Manage: API를 통해 팀 간 플랫폼 전역 사용자 정의 툴킷을 생성하고 공유. 슈퍼 관리자 헤더의 Admin Assistant를 사용하는 데도 필요. |
현재 대시보드만 제어하는 권한
이러한 리소스는 해당 탭을 나타나게 하지만, 기반 API는 여전히 전체 슈퍼 관리자에게만 제한됩니다. 이것들만 부여받은 사용자는 탭을 보게 된 후 로드 시 "Unauthorized" 오류에 부딪힙니다.
아직 이것들로 위임 역할을 구축하지 마세요. 매트릭스가 신비로워 보이지 않도록 여기에 나열한 것뿐입니다.
| 리소스 | 드러내는 탭 | 상태 |
|---|---|---|
| Overview | (없음) | 전혀 효과 없음. Overview 탭은 어차피 전체 슈퍼 관리자 전용입니다. |
| Agents | Agents | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
| SSO Configuration | SSO Configuration | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
| Knowledge Base | Knowledge Base | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
| Templates | Agent Templates, Workflow Templates, Project Templates | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
| Toolkits | Toolkits | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
| Secrets | Secrets, Vault | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
| Platform Settings | Platform Settings | UI 게이트만 — API는 전체 슈퍼 관리자 필요. |
절대 위임할 수 없는 표면
이들은 매트릭스에 권한이 없으며 설계상 전체 슈퍼 관리자 전용입니다: Overview, App Licenses, Teams Bots, LLM Metrics, LLM Usage, Extraction Usage, Email Configuration, KB Decryption Service, Migrations, System, Task Monitor, Global Notifications, Custom Python Packages.
Custom Python Packages는 패키지 설치가 어플라이언스 호스트에서 임의 코드를 실행하므로 의도적으로 제외되고 전체 슈퍼 관리자에게 영구적으로 잠겨 있습니다.
역할이 볼 수 있는 탭
두 가지 다른 규칙이 적용되며, 이는 역할을 구축할 때 가장 흔한 혼란의 원천입니다.
| 규칙 | 리소스 | 동작 |
|---|---|---|
| View로 충분 | Users, Teams, Access Controls, Logs & Auditing, Admin Roles | View를 부여하면 안전한 읽기 전용 상태로 탭이 드러납니다. Manage를 부여하면 완전히 상호작용 가능해집니다. |
| Manage 필수 | Projects, Agents, SSO Configuration, Knowledge Base, Templates, Toolkits, Custom Toolkits, Secrets, Platform Settings | View만 부여하면 탭이 숨겨집니다. 이 탭들은 아직 읽기 전용 처리가 없어, view-only 권한은 사용자가 눌러서는 안 되는 실시간 버튼을 표시하게 됩니다. |
Projects에 View를 체크했는데 탭이 나타나지 않는다면 그 이유입니다. Manage를 체크하세요.
읽기 전용이 실제로 어떻게 보이는지
읽기 전용 모드를 알리는 배너나 배지가 없습니다. 컨트롤이 단지 없거나 회색으로 표시될 뿐입니다.
| 탭 | 완전히 숨김 | 비활성(표시되지만 회색) | 여전히 사용 가능 |
|---|---|---|---|
| Users | Create User, Export, Delete User | 관리자 역할 할당 피커, 대기 중인 재활성화 요청의 승인/거부 | 검색, 탐색, 역할 배지, View Team, View SAML, 로그인 IP 세부 정보, 페이지네이션 |
| Teams | Create Team, Edit Team, Delete Team, Renew Licence, Add/Remove Member, Transfer Ownership, Edit Settings, Automated Management 아래 규칙 편집, Team Logs/Audit의 Export | — | 팀 검색 및 필터, 모든 팀 세부 정보, 멤버 목록(역할은 일반 텍스트로 표시), 설정, 결제, 로그 및 감사 탐색 |
| Access Controls | 규칙 편집·삭제 아이콘, "Add New Rule" 섹션 전체 | "Allow Any New Users" 카드, "Restrict to SAML Metadata" 카드, "Require pre-authorized account" 스위치 | 현재 모드, 제한 모드 경고, 기존의 모든 SAML 규칙 |
| Logs & Auditing | 모든 감사 뷰의 Export, 감사 기능 카드의 Enable 스위치 | — | 모든 필터, 탐색, 행 확장, 세부 모달, Load More |
| Admin Roles | New Role, Save, Delete | 이름 및 설명 필드, 모든 권한 체크박스 | 역할 목록, 그리고 비활성 편집기로 역할을 여는 View 버튼 |
단계별
사용자 정의 역할 만들기
- Super Admin → Security & access → Admin Roles로 이동합니다.
- New Role을 클릭합니다.
- Name을 입력합니다(예: Support Tier 2). 이것이 역할 피커에 표시됩니다. 내부 ID는 이름에서 자동 생성됩니다 — 소문자로, 공백과 문장 부호는 밑줄로 대체됩니다.
- Description을 입력합니다. 역할 테이블에서 이름 아래에 표시됩니다. 자신이 아니라 다음 관리자를 위해 작성하세요.
- 권한 매트릭스에서 리소스별 원하는 동작을 체크합니다. 기억하세요: Manage는 View를 함의하므로 둘 다 필요 없습니다. Users / Teams / Access Controls / Logs & Auditing / Admin Roles 밖의 어떤 것이든 탭이 나타나려면 Manage를 체크해야 합니다. 위의 대시보드 전용 목록에 있는 것은 아직 처음부터 끝까지 작동하지 않습니다.
- Save를 클릭합니다.
새 역할은 테이블에 Custom으로 표시되고 Users 탭의 역할 피커에 즉시 제공됩니다.
역할 편집 또는 삭제
- 편집 — 사용자 정의 역할의 Edit을 클릭하고 필요한 것을 변경한 다음 Save를 클릭합니다.
- 시스템 역할 — 버튼이 Edit 대신 View로 표시되고 매트릭스가 잠깁니다. 이름과 설명은 여전히 변경할 수 있지만 권한은 변경할 수 없습니다.
- 삭제 — 사용자 정의 역할의 Delete를 클릭하고 확인합니다. 현재 보유한 사용자는 조용히 할당 해제되어 Super Admin 접근이 전혀 없게 됩니다. 재할당 프롬프트가 없으므로 삭제 전에 누가 그 역할을 보유하고 있는지 확인하세요.
사용자에게 역할 할당
- Super Admin → Users & workspaces → Users로 이동합니다.
- 사용자를 찾습니다(검색은 사용자 ID, 이메일 또는 이름을 허용).
- 해당 행에서 Assign admin role 드롭다운을 열고 역할을 선택하거나, 모든 Super Admin 접근을 철회하려면 No admin role을 선택합니다.
- 프롬프트를 확인합니다. 플랫폼 전체 권한의 부여/철회는 의도적으로 확인 단계를 거치며, 본인을 강등하면 추가 경고가 있습니다 — 즉시 Super Admin 대시보드 접근을 잃고 복구하려면 다른 슈퍼 관리자가 필요합니다.
사용자는 최대 하나의 관리자 역할을 가집니다. 새 역할을 할당하면 이전 역할을 대체합니다.
여기에는 두 개의 권한이 관여합니다: Admin Roles → View는 피커가 채워지기 위해 필요하며(없으면 드롭다운이 회색으로 표시되고 사용자의 현재 역할이 일반 레이블로 표시됩니다 — 내장 UAM 역할이 관리자 역할을 할당할 수 없는 이유가 여기에 있습니다), Admin Roles → Manage는 실제로 누구의 역할을든 변경하기 위해 필요합니다.
변경이 적용되는 시기 알기
- 다른 사람에 대해 행동하는 당신: 즉시. 서버는 모든 요청에서 권한을 다시 해석하므로, 철회는 영향받는 사용자의 다음 API 호출을 차단합니다.
- 영향받는 사용자의 브라우저: 사이드바와 탐색은 로그인 시 가져오고 로컬에 캐시한 권한 데이터로 그려집니다. 탭이 나타나거나 사라지려면 페이지를 새로 고침해야 합니다(또는 로그아웃 후 다시 로그인).
역할을 변경한 후 사용자에게 새로 고침을 안내하세요.
고려해야 할 동작과 제한
탭 표시 비대칭
View는 단 다섯 개의 탭(Users, Teams, Access Controls, Logs & Auditing, Admin Roles)만 드러냅니다. 나머지는 모두 Manage가 필요합니다. 최소 권한 역할을 설계할 때 이를 감안하세요.
UAM 역할은 UI에서 팀 또는 프로젝트 구성을 관리할 수 없습니다
그 user_manage 권한은 API 수준에서는 실재하지만 Teams 탭은 읽기 전용으로 렌더링되고 Projects 탭은 숨겨집니다. UI 기반 팀 구성 관리가 요구 사항이라면 사용자 정의 역할에서 Teams → Manage를 사용하세요.
감사 로그 내보내기는 위임할 수 없습니다
Logs & Auditing → Export을 체크하면 내보내기 버튼의 숨김은 해제되지만, 모든 감사 내보내기 엔드포인트는 여전히 전체 슈퍼 관리자를 요구하므로 다운로드가 "Unauthorized"로 실패합니다. 당분간 감사 내보내기는 전체 슈퍼 관리자 전용으로 취급하세요. 읽기 접근은 제대로 위임됩니다.
여러 매트릭스 리소스가 대시보드 전용입니다
Agents, SSO Configuration, Knowledge Base, Templates, Toolkits, Secrets, Platform Settings는 탭을 드러내지만 API는 여전히 전체 슈퍼 관리자를 요구합니다. Overview는 아무것도 하지 않습니다.
레거시 플래그는 여전히 존재하며 동기화됩니다
Super Admin을 할당하면 레거시 슈퍼 관리자 플래그가 설정되고, Monitoring을 할당하면 레거시 모니터링 플래그가 설정되며, 다른 역할을 할당하거나 역할을 비우면 둘 다 지워집니다. 이런 플래그를 직접 관리할 필요도 없고 하려고 해서도 안 됩니다 — 역할 할당이 유일하게 지원되는 경로입니다.
자기 자신을 잠그는 것을 막아주는 것은 아무것도 없습니다. 관리자는 자신의 Super Admin 역할을 제거할 수 있습니다. 확인 대화 상자가 경고하지만 이 동작은 허용됩니다. 모든 배포에 전체 슈퍼 관리자를 최소 두 명 유지하세요.
레시피
| 요구 사항 | 구성 |
|---|---|
| 사람을 조회할 수는 있지만 아무것도 변경할 수 없는 헬프 데스크 | 사용자 정의 역할: Users → View |
| 계정 편집과 비활성화까지 가능한 헬프 데스크 | 사용자 정의 역할: Users → Manage |
| 아이덴티티 관리자 (내장 UAM 형태) | User Access Manager 할당, 또는 Users → Manage, Access Controls → Manage가 있는 사용자 정의 역할 |
| 관리자 역할도 할당 가능한 아이덴티티 관리자 | 사용자 정의 역할: Users → Manage, Access Controls → Manage, Admin Roles → Manage |
| Teams 탭에서 구성을 관리하는 팀 관리자 | 사용자 정의 역할: Teams → Manage (User mgmt만으로는 부족) |
| 프로젝트 관리자 | Project Manager 할당, 또는 Projects → Manage가 있는 사용자 정의 역할 |
| 컴플라이언스 / 감사 독자 | Monitoring 할당, 또는 Logs & Auditing → View가 있는 사용자 정의 역할. 내보내기는 위임 불가. |
| 사용자와 팀 기록도 읽어야 하는 감사자 | 사용자 정의 역할: Logs & Auditing → View, Users → View, Teams → View |
감사
모든 관리자 역할 변경은 슈퍼 관리자 동작 감사 로그에 기록되며, Super Admin → Usage & auditing → Logs & Auditing → Super Admin audits에서 볼 수 있습니다.
| 이벤트 | 기록 시점 |
|---|---|
admin_role_created | 사용자 정의 역할 생성 (권한 맵 포함) |
admin_role_updated | 역할의 이름, 설명 또는 권한 변경 |
admin_role_deleted | 사용자 정의 역할 삭제 |
super_admin_granted / super_admin_revoked | 사용자가 전체 Super Admin 역할을 얻거나 잃음 |
monitoring_role_granted / monitoring_role_revoked | 사용자가 Monitoring 역할을 얻거나 잃음 |
admin_role_changed | 기타 모든 역할 할당 변경, 이전 및 새 역할 기록 |
역할 할당 이벤트는 수행자, 대상 사용자, 변경 전/후 역할을 기록합니다.
테스트 체크리스트
- 좁은 단일 권한(예: Users → View)으로 테스트용 사용자 정의 역할을 만들고 테스트 계정에 읽기 전용으로 탭이 나타나는지 확인
- Manage 전용 리소스(예: Projects)가 View만 부여되었을 때는 숨겨지고 Manage가 부여되면 나타나는지 확인
- 테스트 사용자에게 역할을 할당한 후 사이드바가 업데이트되려면 브라우저를 새로 고쳐야 하는지 확인
- 시스템 역할의 권한을 편집하려 시도하고 거부되는지 확인
- 현재 누군가에게 할당된 사용자 정의 역할을 삭제하고 조용히 관리자 역할 없음으로 떨어지는지 확인
- 각 역할 변경이 슈퍼 관리자 감사 로그에 올바르게 나타나는지 확인
- 어떤 사용자 정의 역할이든 부여하기 전에 최소 두 계정이 전체 Super Admin을 보유하는지 확인
문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| 사용자에게 역할이 있지만 탐색에 Super Admin 항목이 없음 | 역할이 표시 가능한 탭에 대응하는 아무것도 부여하지 않음(예: Manage 제한 리소스의 View만), 또는 브라우저에 오래된 권한이 캐시됨 | 위의 권한 레퍼런스와 역할 대조; 사용자에게 페이지 새로 고침 안내 |
| 부여한 탭이 나타나지 않음 | 리소스가 표시되려면 Manage 필요 | View 대신 Manage를 체크 |
| 탭은 나타나지만 모든 것이 "Unauthorized"로 실패 | 리소스가 대시보드만 제어 | 위의 대시보드 전용 목록 참조 — 그 리소스는 아직 위임 불가 |
| 사용자가 열 수 있는 탭에 버튼이 없음 | 탭이 읽기 전용 모드: View는 있지만 Manage 없음 | 해당 리소스에 Manage 부여 |
| Logs & Auditing에 내보내기 버튼이 없음 | 읽기 전용 모드 — Export 권한 없음 | Export 부여. 단, 다운로드는 여전히 실패합니다(감사 내보내기는 위임 불가) |
| 내보내기 버튼은 있지만 다운로드 실패 | 감사 내보내기는 전체 슈퍼 관리자 필요 | 위의 "감사 로그 내보내기는 위임할 수 없습니다" 참조 |
| Assign admin role 드롭다운이 회색 | 행동하는 관리자에게 Admin Roles → View가 없어 역할 목록을 로드할 수 없음 | Admin Roles → View 부여 (그리고 역할을 실제로 변경하려면 Manage) |
| 사용자의 관리자 역할 변경이 "Unauthorized" 반환 | 행동하는 관리자에게 Admin Roles → Manage가 없음 | Admin Roles → Manage 부여 |
| "Cannot modify the permissions of a system role" | 시스템 역할 권한은 고정 | 원하는 권한으로 사용자 정의 역할 생성 |
| "Cannot delete a system role" | 네 개의 내장 역할은 보호됨 | 대신 사용자에게서 할당 해제 |
| 역할 변경이 사용자에게 적용되지 않음 | 클라이언트가 이전 권한을 캐시함 | 새로 고침하거나 로그아웃 후 다시 로그인하게 함 |
| 기존 슈퍼 관리자가 업그레이드 후 접근 상실 | 발생해서는 안 됨 — 기존 보유자는 자동 마이그레이션됨 | 다른 전체 슈퍼 관리자 계정으로 Users 탭에서 Super Admin 역할을 다시 할당 |
운영 지침
업그레이드 동작
기능이 배포되면 기존 권한 보유자가 자동으로 마이그레이션됩니다:
- 레거시 슈퍼 관리자 플래그가 있는 계정은 Super Admin 역할을 할당받습니다.
- 레거시 모니터링 플래그만 있는 계정은 Monitoring 역할을 할당받습니다.
- 다른 모든 계정은 관리자 역할 없이 남습니다.
별도의 동작이 필요 없으며 업그레이드 중 누구도 접근을 잃지 않습니다.
API 레퍼런스
모든 엔드포인트는 관리자 API 아래에 있으며 명시된 권한을 보유한 사용자의 베어러 토큰이 필요합니다.
| 메서드 및 경로 | 권한 | 목적 |
|---|---|---|
GET /admin/permissions | roles:view | 리소스 카탈로그와 각각에 유효한 동작 — 역할 빌더가 렌더링하는 것 |
GET /admin/roles | roles:view | 모든 역할 나열 |
POST /admin/roles | roles:manage | 사용자 정의 역할 생성 |
PUT /admin/roles/{role_id} | roles:manage | 역할 업데이트 (시스템 역할은 권한 거부) |
DELETE /admin/roles/{role_id} | roles:manage | 사용자 정의 역할 삭제 (시스템 역할 거부) |
{"admin_role_id": "..."}와 함께 PUT /admin/users/{user_id} | roles:manage | 역할 할당; null은 해제 |
GET /user/info | authenticated | 호출자의 admin_role_id와 유효한 admin_permissions 반환 |
역할의 권한은 리소스를 동작 목록에 매핑하는 JSON 객체입니다. 전체 접근 와일드카드는 {"*": ["*"]}입니다. 알 수 없는 리소스 또는 그 리소스에 유효하지 않은 동작으로 역할을 만들면 HTTP 400으로 거부됩니다.
예제 — 내장 User Access Manager:
{
"access_controls": ["view", "manage"],
"users": ["view", "manage"],
"teams": ["user_manage"],
"projects": ["user_manage"]
}
예제 — 읽기 전용 헬프 데스크 역할 생성:
POST /admin/roles
{
"name": "Help Desk",
"description": "Read-only access to user records for first-line support.",
"permissions": { "users": ["view"] }
}
권한 매트릭스 한눈에 보기
| 리소스 | View | Manage | User mgmt | Export | 탭이 나타나는 조건 | 완전히 강제 |
|---|---|---|---|---|---|---|
| Overview | ✓ | — | — | — | 언제나 | 효과 없음 |
| Users | ✓ | ✓ | — | — | View | 예 |
| Teams | ✓ | ✓ | ✓ | — | View | 예 |
| Projects | ✓ | ✓ | ✓ | — | Manage | 예 |
| Agents | ✓ | ✓ | — | — | Manage | UI만 |
| Access Controls | ✓ | ✓ | — | — | View | 예 |
| SSO Configuration | ✓ | ✓ | — | — | Manage | UI만 |
| Logs & Auditing | ✓ | — | — | ✓ | View | view만 |
| Knowledge Base | ✓ | ✓ | — | — | Manage | UI만 |
| Templates | ✓ | ✓ | — | — | Manage | UI만 |
| Toolkits | ✓ | ✓ | — | — | Manage | UI만 |
| Custom Toolkits | ✓ | ✓ | — | — | 탭 없음 | 예 (API) |
| Secrets | ✓ | ✓ | — | — | Manage | UI만 |
| Platform Settings | ✓ | ✓ | — | — | Manage | UI만 |
| Admin Roles | ✓ | ✓ | — | — | View | 예 |
문서 버전 1.0 — 출시된 상태의 슈퍼 관리자 RBAC 기능과 이후 수정 사항을 다룹니다. 위에 설명된 대시보드 전용 권한과 감사 내보내기 제한은 작성 시점의 알려진 한계를 반영하므로, 의존하기 전에 배포된 릴리스와 대조 검증하세요.