# 유저 그룹 기반 ReBAC 권한 아키텍처 (User Group-based ReBAC)

이 문서는 Baron SSO의 이슈 #239를 통해 구현된 유저 그룹 중심의 권한 체계와 Ory Keto를 이용한 ReBAC(Relationship-Based Access Control) 설계 방식을 설명합니다.

## 1. 개요
기존의 '테넌트 그룹(Tenant Group)' 방식에서 '유저 그룹(User Group)' 방식으로 전환하여, 권한 부여의 주체(Subject)를 그룹화하고 자원(Tenant)에 대한 권한을 상속받는 구조로 설계되었습니다.

## 2. 권한 상속 다이어그램

```mermaid
graph TD
    %% Entities
    subgraph Identity [사용자 계정]
        U1[User: A]
        U2[User: B]
    end

    subgraph Subjects [권한 부여 주체]
        UG[User Group: 개발팀]
    end

    subgraph Resources [보호 대상 자원]
        T1[Tenant: Project Alpha]
        T2[Tenant: Project Beta]
        RP[Relying Party: Auth App]
    end

    %% Relationships
    U1 -- "is member of" --> UG
    U2 -- "is member of" --> UG

    UG -- "assigned role: manage" --> T1
    UG -- "assigned role: view" --> T2

    %% Inheritance Logic (Keto ReBAC)
    T1 -- "owns" --> RP
    
    %% Direct Inheritance
    U1 -. "inherits: manage" .-> T1
    U1 -. "inherits: view" .-> T2
    U2 -. "inherits: manage" .-> T1
    
    %% Recursive Permission
    T1 -. "allows access" .-> RP
    U1 -. "can manage" .-> RP

    %% Styles
    style Identity fill:#f9f,stroke:#333,stroke-width:2px
    style Subjects fill:#bbf,stroke:#333,stroke-width:2px
    style Resources fill:#dfd,stroke:#333,stroke-width:2px
    linkStyle 4,5,6,7,8,9 stroke:#ff944d,stroke-width:2px,stroke-dasharray: 5 5
```

## 3. 기술적 관계 설계 (Ory Keto Tuples)

Ory Keto 내부적으로는 다음과 같은 관계 튜플(Relationship Tuples)을 통해 권한을 관리합니다.

### 3.1 그룹 멤버십 (Group Membership)
사용자를 특정 유저 그룹의 멤버로 등록합니다.
- **Tuple:** `Tenant:<GroupID>#members@User:<UserID>`
- **의미:** `GroupID`에 해당하는 유저 그룹 tenant의 멤버로 `UserID` 사용자를 등록한다.

### 3.2 테넌트 권한 할당 (Tenant Role Assignment)
유저 그룹 전체에 특정 테넌트에 대한 역할을 부여합니다.
- **Tuple:** `Tenant:<TenantID>#<Relation>@Tenant:<GroupID>#members`
- **의미:** `GroupID` 유저 그룹 tenant의 모든 멤버는 `TenantID` 테넌트에 대해 `<Relation>`(예: `view`, `manage`, `admins`) 권한을 가진다.

### 3.3 자원 소유 및 전파 (Resource Ownership)
테넌트가 소유한 하위 자원(RP, API Key 등)에 대한 권한 전파 규칙입니다.
- **Tuple:** `RelyingParty:<ClientID>#parents@Tenant:<TenantID>`
- **검증 논리:** 사용자가 `ClientID`에 대한 `view` 권한을 요청하면, Keto는 해당 사용자가 부모인 `TenantID`에 대해 `view` 권한이 있는지 역추적하여 승인합니다.

## 4. 주요 장점

1. **중앙 집중식 관리:** 사용자의 부서 이동이나 퇴사 시, 개별 테넌트의 권한을 수정할 필요 없이 유저 그룹의 멤버십만 변경하면 모든 연관 권한이 즉시 회수/부여됩니다.
2. **복합 권한 구성:** 하나의 그룹이 여러 테넌트에 대해 서로 다른 수준의 권한을 가질 수 있어, 실제 조직 구조와 프로젝트 협업 모델을 유연하게 반영할 수 있습니다.
3. **Zanzibar 스타일 확장성:** Google Zanzibar 논리를 따르는 Ory Keto를 활용함으로써, 향후 수만 명의 사용자와 수천 개의 테넌트 환경에서도 성능 저하 없이 정교한 권한 체크가 가능합니다.

## 5. 현재 구현 기준 주의사항

- 현재 Baron SSO는 별도 `UserGroup` namespace를 사용하지 않습니다.
- 유저 그룹은 `Tenant` namespace 내부의 특수 tenant(`type = USER_GROUP`)로 표현합니다.
- 따라서 group membership과 group-based role assignment는 모두 `Tenant:<groupId>#members` subject set을 기준으로 해석해야 합니다.

## 6. 관련 구현 파일
- **Backend Service:** `backend/internal/service/user_group_service.go`
- **Backend Handler:** `backend/internal/handler/user_group_handler.go`
- **Frontend API:** `adminfront/src/lib/adminApi.ts`
- **Frontend UI:** `adminfront/src/features/user-groups/`