4. 권한#

KADA REST API는 Global Authority (전역 권한)와 ACL (Access Control List)이 결합된 하이브리드 권한 모델을 사용한다.

Global Authority: API Key 에 부여된 전역 권한으로, 시스템에서 수행할 수 있는 작업의 범위를 정의한다. (예: READ, WRITE, CREATE, DROP, SHARED, ADMIN)
ACL(Access Control List): 컬렉션별로 특정 사용자에게 부여하는 접근 권한이다. 자세한 내용은 8장. 컬렉션 접근 권한 관리(Shared Access)를 참고한다.

4.1 권한 종류#

4.1.1 권한 목록#

권한	설명	주요 용도
READ	조회 전용	- 컬렉션 목록 조회 - 컬렉션 상세 조회 - 문서 조회 (전체/단건 검색, JSONPath) - 문서 개수 조회
WRITE	쓰기 권한	- 문서 삽입 (단건, 다건) - 문서 수정 (교체) - 문서 삭제 (단건, 다건, 조건부)
CREATE	컬렉션 생성	- 일반 컬렉션 생성 - 컬렉션 공유 권한 부여
DROP	컬렉션 삭제	- 컬렉션 삭제 - 컬렉션 공유 권한 회수
SHARED	공유 컬렉션 전용 권한	- 공유 컬렉션(`shared=true` 컬렉션) 생성/조회/삭제 - 공유 컬렉션(`shared=true` 컬렉션) 의 메타데이터 조회, 문서 조회, 쓰기, 삭제
ADMIN	시스템 관리자	- 모든 권한 포함 (READ, WRITE, CREATE, DROP, SHARED) - API Key 관리 (생성, 조회, 삭제, 권한 수정) - 모든 사용자의 컬렉션 접근 가능

4.1.2 권한 주의 사항#

GET /collections/shared-with-me ( READ, SHARED, ADMIN 중 하나로 접근 할수 있다.)
WRITE 권한은 READ 권한을 포함하지 않는다. 따라서 컬렉션 목록 조회와 같이 READ 권한을 명시적으로 요구하는 API를 사용하려면 READ 권한을 별도로 부여해야 한다. 즉, 'WRITE' 권한만으로는 이러한 API를 호출할 수 없다.
단, 컬렉션 메타데이터 조회, 문서 조회/검색/카운트 API는 WRITE 권한만으로도 호출할 수 있다.
공유 컬렉션(shared=true 컬렉션)은 CREATE만으로 생성할 수 없고, SHARED 또는 ADMIN 권한이 필요하다.
공유 컬렉션(shared=true 컬렉션)은 DROP만으로 삭제할 수 없고, SHARED 또는 ADMIN 권한으로 삭제할 수 있다.
SHARED권한은 ACL로 공유받은 private 컬렉션 접근 자체를 의미하는 권한은 아니다.

4.1.3 권한 조합 예시#

용도	권한 조합
읽기 전용 클라이언트	READ
일반 사용자	READ, WRITE
컬렉션 관리자	READ, WRITE, CREATE, DROP
공유 컬렉션 전용 사용자	SHARED
공유 컬렉션 조회 가능 사용자	READ/WRITE/SHARED
전체 관리자	ADMIN

4.2 권한 체크 방식 및 우선 순위#

4.2.1 권한 체크 방식#

본인 컬렉션 접근: JWT에 포함된 Global Authority로 빠르게 검증
타인 컬렉션 접근: ACL 테이블(shared_access)에서 공유 권한 확인
ADMIN 권한: 모든 리소스에 대한 전체 접근 허용

4.2.2 우선 순위#

ADMIN 권한은 모든 리소스에 대한 접근을 허용한다.
본인 컬렉션 리소스는 JWT 토큰(또는 IdP 토큰)의 Global Authority로 확인한다.
타인 컬렉션 문서 접근은 ACL 테이블에서 공유 권한을 확인한다.
공유 컬렉션(shared=true 컬렉션)은 SHARED 또는 ADMIN 권한으로 생성/삭제/쓰기 작업을 할 수 있다.
공유 컬렉션(shared=true 컬렉션)의 읽기 및 메타데이터 조회는 READ, WRITE, SHARED, ADMIN으로 가능하다.
컬렉션/문서 리소스의 조회는 WRITE 권한으로도 가능하다.

4.3 크로스 유저 접근#

다른 사용자의 컬렉션에 접근하려면, 해당 컬렉션 소유자가 ACL을 통해 권한을 부여해야 한다. 8장의 컬렉션 공유(Shared Access) API를 참고한다. 공유받은 컬렉션은 {소유자ID}.{컬렉션이름} 형식으로 접근한다.

예) userA의 order 컬렉션: userA.orders

{소유자ID}.{컬렉션이름} 형식으로는 컬렉션의 메타데이터 조회를 할 수 없다.

예제#

다음은 userA가 userB에게 orders 컬렉션 접근 권한으로 READ 권한을 부여하고, userB가 해당 컬렉션을 조회하는 예제이다.

# 1. userA가 userB에게 orders 컬렉션 READ 권한 부여
# (userA의 토큰으로)
curl -X POST http://localhost:8080/api/collections/orders/grant \
  -H "Authorization: Bearer ${USER_A_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ 
        "grantTo": "userB", 
        "permission": "READ"
      }'

# 2. userB가 위에서 부여받은 권한으로 userA의 orders 컬렉션 조회
# (userB의 토큰으로)
curl -X GET http://localhost:8080/api/collections/userA.orders/documents \
  -H "Authorization: Bearer ${USER_B_TOKEN}"

4.4 API 엔드포인트별 필요 권한#

인증 API(/auth) - LOCAL 모드 전용#

HTTP	엔드포인트	필요 권한	설명
POST	/auth/token	없음 (API Key 인증)	JWT 토큰 발급
POST	/auth/refresh	없음 (Refresh Token)	Access Token 갱신
POST	/auth/logout	인증 필요	로그아웃

초기 설정 API(/setup) - LOCAL 모드 전용#

HTTP	엔드포인트	필요 권한	설명
GET	/setup/status	없음	초기 설정 필요 여부 조회
POST	/setup/initalize	Setup Token	초기 Admin API Key 생성

컬렉션 API(/collections)#

아래 표에서 일반 컬렉션은 일반, 공유 컬렉션(shared=ture 컬렉션)은 공유로 표기

HTTP	엔드포인트	필요 권한	설명
POST	/collections	- 일반: CREATE/ADMIN - 공유: SHARED/ADMIN	컬렉션 생성
GET	/collections	READ, ADMIN	컬렉션 목록 조회
GET	/collections/{name}	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	컬렉션 메타데이터 조회
DELETE	/collections/{name}	- 일반: DROP/ADMIN - 공유: SHARED/ADMIN	컬렉션 삭제

문서(Document) API#

HTTP	엔드포인트	권한	설명
POST	/collections/{name}/documents	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	단일 문서 삽입
POST	/collections/{name}/documents/batch	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	다중 문서 삽입
GET	/collections/{name}/documents	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	전체 문서 조회
GET	/collections/{name}/documents/{key}	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	키로 문서 조회
POST	/collections/{name}/documents/search	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	조건부 문서 조회
POST	/collections/{name}/documents/jsonpath	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	JsonPath로 문서 조회
PUT	/collections/{name}/documents/{key}	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	키로 문서 교체
PUT	/collections/{name}/documents/replace-one	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	조건부 문서 교체
DELETE	/collections/{name}/documents/{key}	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	키로 문서 삭제
POST	/collections/{name}/documents/delete-one	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	조건부 단일 문서 삭제
POST	/collections/{name}/documents/delete-many	- 일반: WRITE/ADMIN - 공유: SHARED/ADMIN	조건부 다중 문서 삭제
GET	/collections/{name}/documents/count	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	전체 문서 개수
POST	/collections/{name}/documents/count	- 일반: READ/WRITE/ADMIN - 공유: READ/WRITE/SHARED/ADMIN	조건부 문서 개수

컬렉션 공유(Shared Access) API#

HTTP	엔드포인트	필요 권한	설명
POST	/collections/{collectionName}/grant	CREATE/ADMIN	컬렉션 권한 부여
DELETE	/collections/{collectionName}/grant/{userId}	DROP/ADMIN	컬렉션 권한 회수
GET	/collections/grants	READ/ADMIN	내가 부여한 권한 목록
GET	/collections/shared-with-me	READ/ADMIN/SHARED	공유받은 컬렉션 목록

관리자 API (/admin/api-keys) - LOCAL 모드 전용#

HTTP	엔드포인트	필요 권한	설명
POST	/admin/api-keys	ADMIN	API Key 생성
GET	/admin/api-keys	ADMIN	API Key 목록 조회
DELETE	/admin/api-keys/{clientId}	ADMIN	API Key 삭제
PUT	/admin/api-keys/{clientId}/revoke	ADMIN	API Key 폐기
PUT	/admin/api-keys/{clientId}/permissions	ADMIN	API Key 권한 수정
POST	/admin/api-keys/{clientId}/db-account	ADMIN	테넌트 DB 계정 생성

Administrator

Reference

Developer

Tools

External Tools