권한과 역할
App permission을 선언하고 Resource 범위·Policy·테넌트의 grant로 업무 동작을 보호합니다.
권한과 역할
App 동작 보호하기
생성된 permission 선언, 미들웨어, 범위가 적용된 쿼리, Policy를 유지하세요. 새 업무 동작에는 permission을 추가하고, 상태를 변경하기 전에 백엔드에서 동작과 레코드 권한을 검사합니다. 버튼을 숨기는 것은 화면 표현만 바꿉니다.
| 위치 | 맡는 일 |
|---|---|
| Resource Module | App의 동작 key와 권한 계약 선언 |
| Route 미들웨어 | 설치·동작에 필요한 진입 조건 검사 |
| 목록 쿼리 | 행위자가 볼 수 있는 레코드만 반환 |
| Policy·command | Permission·레코드 범위·업무 상태 검사 |
| 프런트엔드 | 가능한 동작 표시와 API의 실제 처리 결과 반영 |
| 테넌트 접근 관리 | Role 구성과 유효한 Access Grant 배정 |
구현 순서와 Route 권한 검사는 보호된 API 추가하기를 참고하세요.
권한을 판단하는 요소
| 요소 | 판단할 내용 | 소유 주체 |
|---|---|---|
| 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 내부의 일부입니다.
public function update(Actor $user, Note $note): bool
{
return $this->allowsPermission($user, 'workshop.note.update')
&& $this->matchesAuthorizationContract($note);
}matchesAuthorizationContract()는 SDK의 ResourceAuthorization::recordMatches()를
호출합니다. 목록은 scopeVisible(), 생성은 해당 소유자 속성을 사용합니다.
각 역할은 보호된 API 추가하기에서 확인하세요.
업무 상태 조건을 추가할 때 기존 검사를 제거하지 않습니다. 생성된 삭제 동작은
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은 권한 묶음의 제안일 뿐입니다. 권한 묶음을 제안하는 것만으로 사용자에게 접근 권한이 부여되지는 않습니다.
화면에서도 Resource 범위 유지하기
테넌트 권한 결과를 법인·운영 조직 리소스의 접근 여부로 대신 사용하지 마세요. 조직 범위 화면은 SDK의 useOrganizationTargetsQuery에 해당 동작의 permission을 전달하여 허용된 대상을 조회합니다. 목록은 생성된 useOrganizationListScope 패턴을 유지하고, 상세·편집은 저장된 레코드의 대상과 API가 반환하는 동작 가능 여부를 따릅니다.
허용된 조직이 하나 있다는 사실만으로 모든 레코드를 열 수 있는 것은 아닙니다. 최종 레코드 접근과 변경 권한은 백엔드 Policy가 검사합니다. 조직 조회 중과 권한 거부도 구분하여 표시하세요.
허용과 거부 함께 확인하기
필요한 grant가 있는 행위자와 없는 행위자로 API를 직접 호출하세요. 허용 범위 밖 레코드와 처리할 수 없는 업무 상태도 확인합니다. 화면에 버튼이 보이는지만으로 접근 제어가 동작한다고 판단하지 않습니다.
설치 후 화면이 안 보이면 Policy를 고치기 전에 grant를 확인하세요. 앱 선언 반영 문제 해결과 App 테스트하기에서 다음 확인 절차를 찾을 수 있습니다.
현재 사용자의 동작 가능 여부 조회
목록 동작 메타데이터는 인증된 현재 사용자의 create 같은 가능 여부를 불리언으로 반환할 수 있으며, 리소스의 read 권한을 요구하지 않습니다. 생성 권한만 가진 사용자도 생성 폼을 사용할 수 있는지 알아야 하기 때문입니다. 레코드, 다른 사용자의 권한, 식별자, 범위 제한 없는 조직 선택지는 반환하면 안 됩니다. 이 응답이 동작 실행을 허가하지는 않으며, 업무 API가 해당 권한과 Policy를 다시 검사합니다. 레코드 동작 메타데이터는 해당 레코드에 대한 접근 권한을 확인해야 합니다.
Core의 인증된 테넌트 API는 런타임 요청을 전달하기 전에 호스트의 요청 빈도 제한을 적용합니다. 생성기가 제공하는 제한된 동작 메타데이터에 앱별 제한기를 추가할 필요는 없습니다. 비용이 크거나 범위가 제한되지 않은 사용자 정의 작업은 별도의 적절한 제한이 필요하며, 위 메타데이터 계약의 예외 대상이 아닙니다.