본문으로 건너뛰기

/admin/workspaces Admin UI

Epic #1362 W2 Step 6 로 도입된 admin 페이지. Keycloak 콘솔을 직접 사용하지 않고 GenD UI 안에서 워크스페이스·멤버 관리.

진입​

  • 권한: realm_access.roles 에 admin 보유.
  • 경로: /admin/workspaces (또는 TopBar 워크스페이스 드롭다운 → ⚙ 워크스페이스 관리).

비-admin 은 라우터 가드로 차단됩니다.

화면 구성​

  • 헤더: 워크스페이스 관리 제목 + + 신규 워크스페이스 버튼.
  • 카드 그리드: 워크스페이스마다 카드 1개:
    • 표시: name · status 배지 · slug · keycloak_group_path
    • 액션: 편집 · 멤버

신규 워크스페이스 생성​

  1. 우측 상단 + 신규 워크스페이스 클릭.
  2. Dialog 입력:
    • Slug — URL-safe lowercase + hyphen, 1~64자 (예: samsung-card)
    • 이름 — 표시명 (예: 삼성카드)
  3. 생성 클릭 → 서버가 다음을 자동 수행:
    • DB 에 Workspace row 추가
    • Keycloak /tenants/<slug> group 자동 생성 (/tenants parent 도 없으면 생성)
    • 실패 시 DB rollback + 502
  4. 토스트 + 목록 새로고침.

워크스페이스 편집​

카드의 편집 클릭 → Dialog:

  • Slug rename: 새 slug 입력 시:
    • Workspace.id UUID 보존 → 30+ cross-cutting 모델 workspace_id FK 영향 0건.
    • Keycloak group name PUT (그룹 id 보존 → 멤버십 자동 잔류).
    • 실패 시 DB rollback + 400 (중복) 또는 502 (인프라).
  • 이름 변경: 단순 UPDATE.

주의: rename 직후 활성 세션의 JWT 는 옛 slug 를 가집니다. 다음 401/403 시 UI 가 토큰 refresh — 사용자가 보통 30분 내 새 slug 반영.

멤버 관리​

카드의 멤버 클릭 → Dialog:

  • 상단 입력: Keycloak user ID (sub UUID) + 추가 버튼
    • 입력 후 추가 → 서버가 사용자의 Keycloak groups 에 /tenants/<slug> 추가 (set-based idempotent)
    • 이미 멤버면 already_member 응답, no-op
  • 하단 목록: 현재 멤버 (username · email) + 휴지통 버튼 → 즉시 제거

user_id 찾기​

Keycloak 사용자 sub:

# admin 토큰 발급 (Master realm)
ADMIN_TOKEN=$(curl -sS ... password grant ...)

# 사용자 검색
curl https://gend.genon.ai/auth/admin/realms/gend/users?username=ttagu99 \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq '.[0].id'

또는 gend admin 페이지의 /admin/users 에서 사용자 row 클릭 → 디테일 드로어에 sub 표시.

Audit​

다음 액션이 AuditMiddleware 에 자동 기록:

  • workspace_created
  • workspace_slug_renamed (old_slug → new_slug, admin_actor)
  • workspace_member_added / workspace_member_removed

OpenSearch 의 audit-* 인덱스에서 검색 가능.

알려진 제약​

  • 위임 트리 (본사 → 지사 → 협력사) 는 별도 Epic #1149 (W3) 에서 다룸.
  • 멤버 추가 시 사용자 검색 autocomplete 는 후속 개선 — 현재는 sub 직접 입력.

트러블슈팅​

증상원인해결
Forbidden 403 진입비-adminKeycloak realm role admin 또는 gend-admin 부여
카드 비어있음워크스페이스 0건 또는 list API 실패우측 상단 + 신규 워크스페이스 로 생성
멤버 추가 후 사용자 JWT 변화 없음세션 토큰 만료 전사용자가 로그아웃 → 재로그인 후 JWT 의 groups 갱신
Keycloak group 만 만들어지고 DB row 없음DB commit 실패운영 로그 + workspace-w2-rollout.md 의 sync 도구 사용

관련​