권한과 역할

App 동작 보호하기

생성된 permission 선언, 미들웨어, 범위가 적용된 쿼리, Policy를 유지하세요. 새 업무 동작에는 permission을 추가하고, 상태를 변경하기 전에 백엔드에서 동작과 레코드 권한을 검사합니다. 버튼을 숨기는 것은 화면 표현만 바꿉니다.

위치	맡는 일
Resource Module	App의 동작 key와 권한 계약 선언
Route 미들웨어	설치·동작에 필요한 진입 조건 검사
목록 쿼리	행위자가 볼 수 있는 레코드만 반환
Policy·command	Permission·레코드 범위·업무 상태 검사
프런트엔드	가능한 동작 표시와 API의 실제 처리 결과 반영
테넌트 접근 관리	Role 구성과 유효한 Access Grant 배정

구현 순서는 보호된 API 추가하기, Route 별칭과 인자는 HTTP 미들웨어에 있습니다.

권한을 판단하는 요소

요소	판단할 내용	소유 주체
Permission	어떤 동작인가?	App 또는 Core의 기능 정의
Role	어떤 permission을 함께 묶는가?	테넌트 관리 또는 Core 기본 정의
Grant 범위	어디까지 배정하는가?	Access Grant
대상 모집단	누구의 레코드에 적용하는가?	Access Grant와 Resource가 지원하는 Policy

적용되는 조건이 모두 맞아야 허용합니다. Permission을 정의한다고 사용자에게 배정되지는 않습니다. App 설치는 정의를 사용 가능하게 하지만 업무 grant를 만들지 않습니다. Legal Entity·Operating Unit 멤버십이나 workspace 선택도 grant가 아닙니다.

Permission key는 workshop.note.update처럼 동작을 나타냅니다. 조직이나 모집단을 key에 넣지 마세요. 그러면 App을 변경하지 않고도 테넌트가 지원되는 범위별로 같은 동작을 배정할 수 있습니다.

생성된 Policy 활용하기

stubs/package-resource/policy.stub에서 생성한 Note Policy는 동작 권한과 레코드 범위를 함께 검사합니다. 아래는 필요한 import와 EvaluatesPermissionDecision trait가 이미 있는 생성 Policy 내부의 일부입니다.

코드 예시

PHP

public function update(Actor $user, Note $note): bool
{
    return $this->allowsPermission($user, 'workshop.note.update')
        && $this->matchesAuthorizationContract($note);
}12345

matchesAuthorizationContract()는 SDK의 ResourceAuthorization::recordMatches()를 호출합니다. 목록은 scopeVisible(), 생성은 해당 소유자 속성을 사용합니다. 각 역할은 테넌트와 컨텍스트에서 확인하세요. 업무 상태 조건을 추가할 때 기존 검사를 제거하지 않습니다. 생성된 삭제 동작은 App이 삭제 수명 주기를 명시적으로 구현하기 전까지 거부됩니다.

범위와 모집단

Grant는 Tenant·Legal Entity·Operating Unit 범위를 지원합니다. 하위 조직 포함은 Operating Unit grant에 적용합니다. all, self, direct_reports, legal_entity, operating_unit 등의 모집단은 유효한 grant를 더 좁히며, 지원 여부는 Resource의 권한 계약에 따릅니다. 커스텀 Resource는 해당 레코드 조건을 구현해야 합니다.

하나의 Grant에 묶인 Role은 범위·모집단·유효기간·회수 시점을 공유합니다. 수명 주기가 달라야 하면 별도 배정으로 나눕니다. 보호된 Role의 배정은 승인되어야 grant가 되며, Role preset은 권한 묶음의 제안일 뿐입니다. App에서 제안하는 방법은 Role Preset에 있습니다.

허용과 거부 함께 확인하기

필요한 grant가 있는 행위자와 없는 행위자로 API를 직접 호출하세요. 허용 범위 밖 레코드와 처리할 수 없는 업무 상태도 확인합니다. 화면에 버튼이 보이는지만으로 접근 제어가 동작한다고 판단하지 않습니다.

설치 후 화면이 안 보이면 Policy를 고치기 전에 grant를 확인하세요. 테넌트 컨텍스트 문제 해결과 App 테스트하기에서 다음 확인 절차를 찾을 수 있습니다.