디렉토리 운영·감사 설계
1. 중앙 원장 운영 범위
중앙 디렉토리는 부서와 사용자 원장만 관리한다. 사용자는 Login ID, 이름, 이메일, 직급, 재직 상태, 소속 부서를 가지며 부서는 코드·이름·상위 부서·활성 상태를 가진다. 포털별 사용자그룹, 역할, 메뉴 권한과 리소스 ACL은 중앙에 생성하거나 수정하지 않는다.
부서와 사용자는 version 기반 낙관적 잠금으로 변경한다. 비활성화와 삭제에는 작업 사유가 필요하고, 삭제에는 confirmation: "DELETE"가 필요하다. 부서는 하위 부서와 소속 사용자가 없어야 삭제할 수 있으며, 사용자는 중앙 원장과 연결된 그룹 제약 없이 삭제할 수 있다. 포털은 삭제된 중앙 사용자 ID를 자체 ACL에서 비활성화하거나 정리해야 한다.
조직 개편처럼 여러 부서를 한꺼번에 등록할 때는 조직도 관리 화면의 다량등록을 사용한다. Dept Code, 부서명, 상위 Dept Code, 활성 순서의 줄을 한 번에 검증해 부모를 먼저 저장하고, 등록할 수 없는 줄이 하나라도 있으면 아무것도 저장하지 않는다. 입력 형식·판정 기준·실패 경로는 ORGANIZATION_BULK_REGISTRATION.md에 정리한다.
2. 감사 로그
directory_audit_logs는 중앙 사용자·조직 원장 변경, 운영센터 조치, 포털 권한 요약 수집을 기록한다. before_data와 after_data는 변경 전후의 JSON 스냅샷이며, 포털 권한 요약의 실제 변경은 포털이 소유하므로 중앙에는 수집 메타데이터만 기록한다.
| 필드 | 설명 |
|---|---|
actor_user_id | 독립 관리자 API Key의 설정 ID |
action | DEACTIVATE, DELETE, REMEDIATE, REPLACE_PORTAL_AUTHORIZATION_SNAPSHOT 등 |
entity_type | DEPARTMENT, USER, OPERATIONS, PORTAL_AUTHORIZATION 등 |
entity_id | 중앙 원장 대상 ID 또는 포털 ID |
reason | 운영 작업 사유 또는 수집 목적 |
before_data, after_data | 감사용 전후 스냅샷 |
created_at | UTC 기준 기록 시각 |
3. 서버·tRPC API
관리 tRPC API는 x-directory-admin-key로 인증된 관리자만 호출할 수 있다. OAuth 콜백과 세션 쿠키에 의존하지 않는다.
| Procedure | 목적 |
|---|---|
directory.overview | 활성 사용자와 부서 원장 조회 |
directory.users, directory.departments | 사용자·부서 개별 조회 |
directory.create/update/deactivate/deleteUser | 사용자 원장 관리 |
directory.create/update/deactivate/deleteDepartment | 조직 원장 관리 |
directory.bulkCreateDepartments | 조직도 다량등록 — 최대 500건을 한 트랜잭션으로 등록(부모 우선, 부분 반영 없음) |
directory.portalAuthorizations | 포털별 읽기 전용 그룹·역할·권한 요약 조회 |
directory.syncStatuses | 포털의 중앙 원장 동기화 상태 조회 |
directory.auditLogs | 감사 로그 조회 |
directory.issues, directory.remediateIssue | 사용자 상태·부서 연결 점검 및 조치 |
4. 운영센터
운영센터는 활성 사용자와 재직 상태의 불일치, 활성 사용자의 부서 연결 누락을 HIGH 심각도로 점검한다. 중앙 사용자그룹의 고아 연결이나 빈 그룹은 중앙 모델에서 사라졌으므로 더 이상 점검하지 않는다.
포털 관측 영역은 포털별 사용자 수, 권한 항목 수, 마지막 스냅샷 버전·수집 시각을 보여준다. 개별 사용자를 선택하면 해당 포털이 발행한 업무 그룹, 역할, 권한 요약을 조회할 수 있다. 이 화면은 읽기 전용이며 수정 버튼을 제공하지 않는다.
5. 안전한 조치 기준
| 상황 | 중앙 운영자 조치 | 포털 운영자 조치 |
|---|---|---|
| 사용자 퇴직·비활성 | 중앙 사용자 원장 비활성화와 감사 기록 | 자체 그룹·역할·ACL 회수 |
| 부서 폐지 | 구성원과 하위 조직 이관 후 중앙 부서 폐기 | 해당 부서 기준 포털 정책 재검토 |
| 포털 권한 오류 | 대시보드로 현황 확인만 수행 | 해당 포털에서 그룹·역할·권한 수정 후 새 스냅샷 발행 |
| 중앙 API 장애 | 보호 기능을 허용하지 않는 Fail Closed 정책 유지 | 포털의 자체 권한 정책과 운영 절차에 따라 복구 |
6. 검증과 향후 운영
현재 테스트는 관리자 API Key의 인증 실패, 포털 scope 거부, 중앙 그룹 API 미노출, 사용자·조직 조회, 포털 권한 요약 수집의 portal ID 일치, 동기화 실패 시각을 검증한다. 실제 Document Library·프로세스 포털이 연결되면 포털별 API Key를 사용해 스냅샷 발행부터 중앙 대시보드 표시까지 통합 검증한다.