DevFront RP 관계 설정 문서 작성

2026-04-20 10:31:04 +09:00
parent a79c350831
commit 6322ff5630
3 changed files with 174 additions and 0 deletions
--- a/docs/devfront-rp-relationships-guide.md
+++ b/docs/devfront-rp-relationships-guide.md
@@ -0,0 +1,169 @@
+# DevFront RP 관계 설정 가이드
+
+이 문서는 DevFront의 RP 상세 화면 > `관계` 탭에서 사용자에게 부여할 수 있는 관계 목록과 각 관계가 의미하는 기능 범위를 정리한다.
+
+## 적용 범위
+
+- 대상 namespace: `RelyingParty`
+- 대상 화면: DevFront RP 상세 화면의 `Relationships` 탭
+- 대상 subject: 현재 1차 구현에서는 direct `User:<kratosIdentityId>` assignment
+- 기준 구현:
+  - `docker/ory/keto/namespaces.ts`
+  - `devfront/src/features/clients/ClientRelationsPage.tsx`
+  - `backend/internal/handler/dev_handler.go`
+
+## 기본 원칙
+
+- 관계 탭에서 부여하는 관계는 **DevFront 운영 권한**이다.
+- `RelyingParty#access`는 실제 서비스 로그인/접근 권한이며, DevFront 운영 권한과 별도이다.
+- 아래 관계 중 하나라도 있으면 해당 RP에 대한 기본 조회 권한(`RelyingParty#view`)도 함께 생긴다.
+- `RP 관리자(admins)`는 상위 관리 관계이며, 대부분의 세부 운영 권한을 포함한다.
+- 세부 관계는 필요한 기능만 최소 권한으로 부여할 때 사용한다.
+
+## 관계 목록
+
+| 화면 표시명 | Relation key | 의미 | 주요 허용 기능 |
+|---|---|---|---|
+| RP 관리자 | `admins` | RP 운영 전반을 관리할 수 있는 관리자 관계 | RP 조회, 설정 관리, secret 재발급, JWKS 운영, consent 조회/회수, 관계 조회, 감사 로그 조회, 상태 변경 |
+| RP 생성자 | `creator` | 이 RP를 생성한 운영 주체를 표시하거나 RP 생성 권한 모델에 연결되는 관계 | RP 조회, RP 생성 정책과 연결 |
+| RP 일반 설정 | `config_editor` | RP 이름, Redirect URI, 메타데이터 같은 일반 설정을 수정할 수 있는 관계 | RP 조회, 일반 설정 수정 |
+| 시크릿 재발급 | `secret_rotator` | Client secret 재발급과 rotation을 수행할 수 있는 관계 | RP 조회, client secret 재발급 |
+| JWKS 조회 | `jwks_viewer` | JWKS 상태, 캐시 정보, key summary를 조회할 수 있는 관계 | RP 조회, JWKS 상태/캐시/key summary 조회 |
+| JWKS 운영 | `jwks_operator` | JWKS refresh/revoke 같은 운영 작업을 수행할 수 있는 관계 | RP 조회, JWKS 조회, JWKS refresh/revoke |
+| 동의 조회 | `consent_viewer` | 이 RP의 consent 내역을 조회할 수 있는 관계 | RP 조회, 동의 및 사용자 목록 조회 |
+| 동의 회수 | `consent_revoker` | 이 RP의 consent를 회수할 수 있는 관계 | RP 조회, 동의 조회, 동의 회수 |
+| 관계 조회 | `relationship_viewer` | 이 RP에 부여된 direct relation을 조회할 수 있는 관계 | RP 조회, 관계 목록 조회 |
+| 감사 로그 조회 | `audit_viewer` | 이 RP의 DevFront 감사 로그를 조회할 수 있는 관계 | RP 조회, 해당 RP 감사 로그 조회 |
+| 상태 변경 | `status_operator` | RP 활성/비활성 상태를 변경할 수 있는 관계 | RP 조회, 활성/비활성 상태 변경 |
+
+## Permit 매핑
+
+Keto namespace 기준으로 relation은 다음 permit으로 계산된다.
+
+| Permit | 허용 relation / 조건 | 기능 의미 |
+|---|---|---|
+| `view` | `admins`, `config_editor`, `secret_rotator`, `jwks_viewer`, `jwks_operator`, `consent_viewer`, `consent_revoker`, `relationship_viewer`, `audit_viewer`, `status_operator`, 부모 tenant의 `view` 또는 `view_dev_console` | RP 기본 조회 및 목록 노출 |
+| `manage` | `admins`, 부모 tenant의 `manage` | RP 관리 상위 권한 |
+| `create` | `creator`, 부모 tenant의 `grant_dev_permissions`, `manage` | RP 생성 |
+| `edit_config` | `config_editor`, `manage` | RP 일반 설정 수정 |
+| `rotate_secret` | `secret_rotator`, `manage` | client secret 재발급/회전 |
+| `view_jwks` | `jwks_viewer`, `operate_jwks`, `manage` | JWKS 상태/캐시/key summary 조회 |
+| `operate_jwks` | `jwks_operator`, `manage` | JWKS refresh/revoke |
+| `view_consents` | `consent_viewer`, `revoke_consents`, `manage` | consent 목록/상세 조회 |
+| `revoke_consents` | `consent_revoker`, `manage` | consent 회수 |
+| `view_relationships` | `relationship_viewer`, 부모 tenant의 `grant_dev_permissions`, `manage` | RP 관계 목록 조회 |
+| `view_audit_logs` | `audit_viewer`, `manage` | 해당 RP의 DevFront 감사 로그 조회 |
+| `change_status` | `status_operator`, `manage` | RP 활성/비활성 상태 변경 |
+| `access` | `access`, `manage` | 실제 서비스 로그인/리소스 접근 |
+
+## 권한별 운영 예시
+
+### 특정 사용자가 RP만 조회해야 하는 경우
+
+최소 관계:
+
+- `audit_viewer`, `consent_viewer`, `jwks_viewer` 등 필요한 세부 조회 관계 중 하나
+
+위 세부 관계는 모두 `RelyingParty#view`를 포함하므로, 사용자는 DevFront에서 해당 RP를 볼 수 있다.
+
+### 특정 사용자가 동의 및 사용자 목록만 봐야 하는 경우
+
+부여 관계:
+
+- `consent_viewer`
+
+허용 결과:
+
+- RP 목록/상세 조회
+- `동의 및 사용자 목록` 조회
+
+허용하지 않는 기능:
+
+- 동의 회수
+- secret 재발급
+- JWKS refresh/revoke
+- 관계 부여/회수
+- 상태 변경
+
+### 특정 사용자가 동의를 조회하고 회수도 해야 하는 경우
+
+부여 관계:
+
+- `consent_revoker`
+
+허용 결과:
+
+- `revoke_consents` permit
+- `view_consents` permit도 함께 허용
+
+### 특정 사용자가 감사 로그만 봐야 하는 경우
+
+부여 관계:
+
+- `audit_viewer`
+
+허용 결과:
+
+- RP 목록/상세 조회
+- 해당 RP와 연결된 DevFront 감사 로그 조회
+
+주의:
+
+- 감사 로그 필터링은 audit details의 `target_id` 또는 `client_id`가 RP client id와 일치하는지 기준으로 동작한다.
+- 오래된 로그 또는 일부 경로에서 `target_id`/`client_id`가 누락된 로그는 RP별 권한 사용자에게 보이지 않을 수 있다.
+
+### 특정 사용자를 RP 운영 담당자로 지정해야 하는 경우
+
+부여 관계:
+
+- `admins`
+
+허용 결과:
+
+- `manage` permit
+- 대부분의 세부 운영 권한 허용
+- consent 조회/회수, 감사 로그 조회, 관계 조회, 상태 변경 등 포함
+
+주의:
+
+- `admins`는 강한 권한이다.
+- 단순 조회나 특정 작업만 필요하면 세부 relation을 우선 사용한다.
+
+## 자동 부여 관계
+
+RP 생성 시 `metadata.user_id`가 존재하면 생성자에게 기본 운영 relation 세트가 outbox로 적재된다.
+
+현재 자동 부여 대상:
+
+- `admins`
+- `creator`
+- `config_editor`
+- `secret_rotator`
+- `jwks_viewer`
+- `jwks_operator`
+- `consent_viewer`
+- `consent_revoker`
+- `relationship_viewer`
+- `audit_viewer`
+- `status_operator`
+
+## 관련 tuple 예시
+
+```text
+RelyingParty:client-a#admins@User:user-1
+RelyingParty:client-a#consent_viewer@User:user-2
+RelyingParty:client-a#consent_revoker@User:user-3
+RelyingParty:client-a#audit_viewer@User:user-4
+RelyingParty:client-a#relationship_viewer@User:user-5
+```
+
+## 운영 주의사항
+
+- 관계 부여/회수는 direct Keto write가 아니라 outbox 적재 방식으로 처리한다.
+- 관계를 부여한 직후 실제 Keto 반영까지 worker 처리 지연이 있을 수 있다.
+- 사용자가 DevFront에서 기대 권한을 얻지 못하면 다음을 우선 확인한다.
+  - relation tuple의 subject가 실제 로그인한 Kratos identity id와 같은지
+  - outbox worker가 tuple을 Keto에 반영했는지
+  - 대상 RP의 client id가 tuple object와 같은지
+  - audit/consent 로그에 `client_id` 또는 `target_id`가 정확히 기록되는지
+
--- a/docs/keto-rebac-namespaces-diagram.md
+++ b/docs/keto-rebac-namespaces-diagram.md
@@ -62,6 +62,7 @@ classDiagram
        consent_viewer: User[]
        consent_revoker: User[]
        relationship_viewer: User[]
+        audit_viewer: User[]
        status_operator: User[]
        -- Permits --
        view: admins OR direct operator relations OR parents.view OR parents.view_dev_console
@@ -74,6 +75,7 @@ classDiagram
        view_consents: consent_viewer OR revoke_consents OR manage
        revoke_consents: consent_revoker OR manage
        view_relationships: relationship_viewer OR parents.grant_dev_permissions OR manage
+        view_audit_logs: audit_viewer OR manage
        change_status: status_operator OR manage
        access: access OR manage
    }
@@ -111,6 +113,7 @@ classDiagram
  - `manage` (관리): 앱의 직접 관리자(`admins`) 또는 **이 앱을 소유한 테넌트(parents)에서 관리 권한을 가진 자**가 관리할 수 있습니다.
  - `edit_config`, `rotate_secret`, `operate_jwks`, `revoke_consents`, `change_status`: 각 직접 relation 또는 `manage`로 판정합니다.
  - `view_relationships`: 직접 `relationship_viewer`, 상위 tenant의 `grant_dev_permissions`, 또는 `manage`로 판정합니다.
+  - `view_audit_logs`: 직접 `audit_viewer` 또는 `manage`로 판정합니다.
  - `access` (접근/로그인 가능 여부): 이 앱에 직접 접근 권한을 부여받은 유저/그룹(`access`), 또는 앱을 관리할 수 있는 권한(`manage`)을 가진 사람이 접근할 수 있습니다.
    - _접근 대상(access)은 특정 유저, 특정 테넌트의 전 멤버, 또는 전역 인증된 유저(System:authenticated_users)가 될 수 있습니다._

--- a/docs/keto-rebac-policy-guide.md
+++ b/docs/keto-rebac-policy-guide.md
@@ -48,6 +48,7 @@ RP에 별도의 가상 테넌트를 만들지 않고, 자원 객체 자체의
 - **Consent 조회 권한 부여**: `RelyingParty:<앱ID>#consent_viewer@User:<유저ID>`
 - **Consent 회수 권한 부여**: `RelyingParty:<앱ID>#consent_revoker@User:<유저ID>`
 - **Relationship 조회 권한 부여**: `RelyingParty:<앱ID>#relationship_viewer@User:<유저ID>`
+- **감사 로그 조회 권한 부여**: `RelyingParty:<앱ID>#audit_viewer@User:<유저ID>`
 - **상태 변경 권한 부여**: `RelyingParty:<앱ID>#status_operator@User:<유저ID>`

 ### 3.2.1 RelyingParty permit 원칙
@@ -61,6 +62,7 @@ RP에 별도의 가상 테넌트를 만들지 않고, 자원 객체 자체의
 - `view_consents`: consent 목록/상세 조회 권한
 - `revoke_consents`: consent 회수 권한
 - `view_relationships`: direct / inherited relationship 조회 권한
+- `view_audit_logs`: 해당 RP의 DevFront 감사 로그 조회 권한
 - `change_status`: 활성/비활성 상태 변경 권한
 - `access`: 실제 서비스 로그인 및 리소스 접근 권한