diff --git a/docs/devfront-rp-relationships-guide.md b/docs/devfront-rp-relationships-guide.md new file mode 100644 index 00000000..b6a04fa2 --- /dev/null +++ b/docs/devfront-rp-relationships-guide.md @@ -0,0 +1,169 @@ +# DevFront RP 관계 설정 가이드 + +이 문서는 DevFront의 RP 상세 화면 > `관계` 탭에서 사용자에게 부여할 수 있는 관계 목록과 각 관계가 의미하는 기능 범위를 정리한다. + +## 적용 범위 + +- 대상 namespace: `RelyingParty` +- 대상 화면: DevFront RP 상세 화면의 `Relationships` 탭 +- 대상 subject: 현재 1차 구현에서는 direct `User:` 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`가 정확히 기록되는지 + diff --git a/docs/keto-rebac-namespaces-diagram.md b/docs/keto-rebac-namespaces-diagram.md index c1418a2e..f8ad62c9 100644 --- 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)가 될 수 있습니다._ diff --git a/docs/keto-rebac-policy-guide.md b/docs/keto-rebac-policy-guide.md index 37bdf6f5..e665b765 100644 --- 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`: 실제 서비스 로그인 및 리소스 접근 권한