BaronSSO/baron-sso/docs/rbac-rebac-policy.md

RBAC / ReBAC 미들웨어 정책 정리

1. 목적

• backend/internal/middleware/rbac.go는 **역할 기반(RBAC)**과 **관계 기반(ReBAC, Keto)**을 조합해 접근 제어를 일관되게 적용합니다.
• 핵심 목표는 운영 단순성 + 권한 정밀도의 균형입니다.

2. 구성 요소와 역할

2.1 RequireRole

• 역할(Role) 기반 접근 제어를 담당합니다.
• Super Admin은 즉시 통과합니다.
• 허용된 역할 목록에 포함되지 않으면 차단합니다.
• API Key 인증은 우회합니다(시스템/운영 경로).

2.2 RequireKetoPermission

• Ory Keto(ReBAC) 권한 체크를 수행합니다.
• Super Admin은 즉시 통과합니다.
• Keto의 관계 튜플에 기반해 CheckPermission을 수행합니다.

2.3 RequireTenantMatch

• 사용자가 요청한 테넌트에 대한 관리 자격이 있는지 검증합니다.
• 상속 권한 인정: 사용자의 기본 테넌트뿐만 아니라, 유저 그룹 멤버십이나 그룹장 직책을 통해 상속받은 모든 테넌트를 대상으로 합니다.
• Super Admin 및 유효한 API Key 요청은 통과합니다.

3. ReBAC 기반인데도 RBAC가 필요한 이유

1. 정책 단순화

• Super Admin 같은 전역 정책은 ReBAC로 표현할 수도 있지만, RBAC가 더 빠르고 명확합니다.

2. 운영 경로 단축

• API Key, 배치성 요청 등은 일반 사용자 흐름과 분리해 처리합니다.
• 불필요한 ReBAC 호출을 줄여 장애 전파를 줄입니다.

3. 테넌트 범위 제어의 명확성

• "Tenant Admin은 자기 테넌트만"은 자주 쓰는 규칙으로, 미들웨어 단에서 즉시 판단이 효율적입니다. 유저 그룹 도입 이후에는 "상속받은 모든 관리 대상 테넌트"로 범위가 확장됩니다.

4. 성능 및 안정성

• Keto는 외부 서비스 호출이므로 지연/실패 가능성이 있습니다.
• RBAC로 1차 필터링을 하여 호출 수를 줄입니다.

4. SoT(단일 진실 공급원) 충돌 시 우선순위 정책

4.1 사용자/인증 SoT

• 1순위: Kratos Identity / Session
  • 사용자 식별과 세션 유효성의 최종 판단 기준
• 2순위: Backend 프로필 DB / 캐시
  • Kratos와 동기화가 보장되는 범위에서만 보조 사용

4.2 권한/정책 SoT

• 1순위: Keto(ReBAC) 관계 튜플
  • 리소스 접근 권한의 최종 판단 기준.
  • 유저 그룹 상속: 사용자가 속한 유저 그룹에 부여된 권한은 Keto를 통해 실시간으로 상속됩니다.
  • 그룹장-어드민 연동: 유저 그룹의 장(Leader)은 해당 그룹(테넌트)의 어드민 권한을 자동으로 가집니다.
• 2순위: RBAC(Role)
  • 전역/상위 정책의 단축 규칙.
  • ReBAC와 충돌 시, ReBAC 결과가 항상 우선.

4.3 테넌트 컨텍스트 SoT

• 1순위: 서버 측 프로필 및 상속된 권한 (ManageableTenants)
  • 사용자의 기본 tenantId뿐만 아니라, 유저 그룹을 통해 상속받은 관리 가능 테넌트 목록 전체를 기준으로 판단합니다.
• 2순위: 요청 헤더(X-Tenant-ID)
  • 헤더는 "요청 의도"를 나타내며, ManageableTenants 목록에 포함된 ID여야 합니다.
  • 불일치 시 차단.

4.4 OIDC/RP 정보 SoT

• 1순위: Hydra Client/Consent 데이터
• 2순위: Backend audit details
  • 과거 데이터 재현을 위해 audit details에 client_id/client_name을 기록

5. 충돌 시 처리 원칙 (확정)

1. RBAC는 필터이고, 허용의 최종 판단은 ReBAC

• RBAC 통과는 ReBAC 호출의 전제일 뿐, 허용 조건이 아니다.
• ReBAC 결과가 "허용"이어야만 최종 통과한다.

2. RBAC 통과 + ReBAC 실패 → 차단

• ReBAC가 최종 권한을 가진다.

3. RBAC 실패 + ReBAC 통과 → 차단

• 역할 기반 정책 위반은 즉시 차단한다.

4. Super Admin 예외

• Super Admin이라도 기본 흐름에서는 ReBAC 판단을 거친다.
• 예외가 필요한 API는 별도로 명시하고, 감사 로그에 명확히 남긴다.

5. API Key 우회 범위

• API Key 우회는 최소 범위로 제한한다.
• 우회 대상 API와 사유를 별도 문서로 관리한다.

6. 정책 보완 필요 지점 (결정 필요)

1. Tenant 헤더 불일치 정책

• X-Tenant-ID가 프로필 테넌트와 불일치할 때 차단은 확정
• 테넌트 전환 UI/흐름에 따라 정책 확정 필요

2. API Key 우회 범위 문서화

• 현재는 RequireRole/RequireTenantMatch에서 우회 처리
• 우회 허용 API 목록과 사유를 문서로 고정 필요

7. 관련 코드

• backend/internal/middleware/rbac.go
• backend/internal/handler/auth_handler.go
• backend/internal/service/keto_service.go