접근 제어 목록

엔드포인트: /api/security/

토큰의 명령, 서버, 파일 접근 제어 목록(ACL)을 관리합니다. 콘솔이나 CLI에 로그인한 상태여야 합니다. 개인 API 토큰(alpat-)과 서비스 토큰(alpst-)으로는 이 API를 호출할 수 없습니다. command_acl, server_acl, file_acl scope가 있어도 403 permission_denied를 반환합니다.

Alpacon Cloud에서는 웹 콘솔의 토큰 페이지에 있는 사전 승인된 명령에서 명령 규칙을 설정하세요. 이 목록을 관리하려면 워크스페이스 역할과 별개인 명령 ACL 관리자 권한이 필요합니다. 슈퍼유저라고 해서 이 권한이 자동으로 부여되지는 않습니다. 카드에 명령 ACL 관리자가 관리한다는 안내가 표시되면 명령 ACL 관리자에게 권한을 요청하세요. 브라우저 연결 안내가 표시되면 연결하기를 선택하세요. 이 API가 반환하는 명령 ACL 항목은 토큰으로 실행할 명령을 허용하거나 거부하는 데 쓰이지 않습니다. 일괄 요청을 포함한 모든 명령 ACL 쓰기 요청은 405 command_acl_moved를 반환합니다. 서버와 파일 ACL은 API로 변경할 수 있습니다.

접근 권한과 대상

자신의 개인 토큰 ACL과 관리 권한이 있는 서비스 토큰 ACL을 조회할 수 있습니다. 관리자는 삭제된 애플리케이션의 ACL을 포함해 모든 서비스 토큰 ACL을 볼 수 있습니다. 그 외 사용자는 토큰을 연결할 권한이 있는 애플리케이션의 서비스 토큰만 관리할 수 있으며, 해당 토큰의 기존 서버 ACL에 있는 서버도 모두 조회할 수 있어야 합니다. 서버 ACL 목록에는 삭제된 서버가 나타나지 않습니다.

ACL 하나는 토큰 하나에만 속합니다. token과 service_token 중 하나만 지정하세요. 쓰기 요청의 개인 토큰은 본인 소유이며 활성화된 토큰이어야 하고, 서비스 토큰은 관리 권한이 있으며 승인을 받아 활성화된 토큰이어야 합니다. 대상 서비스 토큰이 승인 대기 중이거나 비활성화되어 있으면 service_token 필드에 400 does_not_exist를 반환합니다. 서버 ACL 일괄 삭제는 비활성화된 토큰도 받습니다. 토큰 종류를 바꾸려면 같은 요청에서 다른 토큰 필드를 비우세요.

서비스 토큰에 ACL을 설정하려면 그 유형에 맞는 scope가 있어야 합니다. 명령 ACL에는 command scope, 파일 ACL에는 uploaded_file 또는 downloaded_file scope, 서버 ACL에는 서버별 제한을 지원하는 리소스의 scope가 필요합니다. 서버 ACL의 대상은 애플리케이션에 허용된 서버 범위에도 포함되어야 합니다. 이 두 조건은 개인 토큰 ACL에는 적용되지 않습니다.

경로

아래 {resource}에는 command-acl, server-acl, file-acl을 사용합니다.

메서드경로응답
GET/api/security/{resource}/200, 페이지로 나눈 ACL 목록
POST/api/security/{resource}/201, 생성한 ACL
GET/api/security/{resource}/{id}/200, ACL
PUT, PATCH/api/security/{resource}/{id}/200, 변경한 ACL
DELETE/api/security/{resource}/{id}/204, 본문 없음
POST/api/security/{resource}/bulk/201, 조건에 맞는 ACL 배열
POST/api/security/{resource}/bulk/delete/200, {"deleted": 2}
POST/api/security/command-acl/bulk/update/200, 변경한 ACL 배열
POST/api/security/file-acl/bulk/update/200, 변경한 ACL 배열

서버 ACL에는 일괄 수정 경로가 없습니다. 일괄 생성 요청에 중복 항목을 보내도 ACL이 중복 생성되지 않습니다. 일괄 삭제와 수정은 조회 권한이 없는 ACL ID를 무시합니다.

요청과 응답 필드

모든 ACL은 id(UUID), token, service_token, 읽기 전용 token_name과 유형별 필드를 반환합니다. 토큰 비밀 키가 아닌 토큰 ID를 보내세요.

명령 ACL

필드유형필수설명
tokenUUID토큰 필드 중 하나본인의 개인 API 토큰 ID
service_tokenUUID토큰 필드 중 하나서비스 토큰 ID
command문자열예최대 255자의 명령 패턴 하나. 연산자, 줄바꿈, 여러 명령은 허용하지 않음
username문자열아니요최대 128자, 기본값은 빈 문자열. 빈 값은 개인 토큰에서는 소유자, 서비스 토큰에서는 모든 사용자에 해당하며 *는 모든 사용자에 해당
groupname문자열아니요최대 128자, 기본값은 빈 문자열. 빈 값이나 *는 모든 그룹에 해당

그 외 사용자 이름과 그룹 값은 정확히 일치해야 합니다. 줄바꿈, 캐리지 리턴, null 문자는 허용하지 않습니다. 명령은 셸 규칙으로 단어를 나눈 뒤 비교합니다. 마지막 단어인 *는 뒤에 오는 하나 이상의 인수에 해당하고, 다른 위치의 *는 단어 하나 안에서 일치 여부를 판단합니다. 따옴표로 감싼 *는 어떤 값과도 일치하지 않습니다. 마지막 고정 문자열 뒤에는 다른 인수가 올 수 없습니다. sudo command를 허용하려면 패턴에 sudo 접두사를 포함해야 합니다.

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": null,
  "service_token": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
  "token_name": "ci-deploy",
  "command": "df -h",
  "username": "deploy",
  "groupname": ""
}

서버 ACL

token 또는 service_token과 필수 필드인 server UUID를 보냅니다. 조회 권한이 있는 서버여야 합니다. 응답의 server는 id, name, os, platform, is_connected, is_deleted가 담긴 객체입니다.

json
{
  "service_token": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
  "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8"
}

파일 ACL

token 또는 service_token과 다음 필드를 보냅니다.

필드유형필수설명
path문자열예최대 512자. *는 임의의 문자와 일치. 제어 문자는 허용하지 않으며, .. 경로는 정규화하되 마지막 와일드카드는 유지
action문자열예upload, download, 둘 다 허용하는 *
username문자열아니요명령 ACL과 같은 비교 규칙 적용. 기본값은 빈 문자열
groupname문자열아니요명령 ACL과 같은 비교 규칙 적용. 기본값은 빈 문자열
json
{
  "service_token": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
  "path": "/srv/releases/*",
  "action": "upload",
  "username": "deploy",
  "groupname": ""
}

일괄 요청

리소스와 작업본문
명령 bulk/token 또는 service_token, 그리고 command와 선택 필드 username, groupname이 있는 객체 1–100개를 담은 items
파일 bulk/token 또는 service_token, 그리고 path, action과 선택 필드 username, groupname이 있는 객체 1–100개를 담은 items
서버 bulk/token 또는 service_token, 그리고 UUID 1–100개를 담은 servers
서버 bulk/delete/token 또는 service_token, 그리고 UUID 1–100개를 담은 servers
명령 또는 파일 bulk/delete/ACL UUID 1–100개를 담은 ids
명령 bulk/update/ACL UUID 1–100개를 담은 ids, 그리고 username, groupname 중 하나 이상
파일 bulk/update/ACL UUID 1–100개를 담은 ids, 그리고 username, groupname, action 중 하나 이상

일괄 생성은 기존 항목을 포함해 요청 조건에 맞는 ACL을 반환합니다. 서버 ACL은 지정한 토큰과 서버에 해당하는 ACL을 반환합니다. 필드 길이 제한은 개별 생성과 같습니다.

예를 들어 서버 ACL은 다음 본문으로 일괄 생성합니다.

http
POST /api/security/server-acl/bulk/
json
{
  "service_token": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
  "servers": ["7e3984de-49ab-4cc6-bcdf-21fbd35858b8"]
}

목록 필터와 페이지 이동

매개변수설명
token개인 토큰 UUID로 필터링
api_tokentoken의 별칭
service_token서비스 토큰 UUID로 필터링
search개인 토큰과 서비스 토큰 이름 검색
page1부터 시작하는 정수 페이지 번호
page_size기본값 15, 최댓값 100. 100보다 큰 값은 100으로 제한
json
{
  "count": 0,
  "current": 1,
  "next": null,
  "previous": null,
  "last": 1,
  "results": []
}

배열에는 ACL 객체가 들어갑니다. next와 previous는 정수 페이지 번호 또는 null입니다. next가 null이 될 때까지 page=next로 다음 페이지를 요청하세요.

오류

상태코드의미
400invalid_input토큰 필드가 둘 다 있거나 둘 다 없음, 잘못된 제어 문자, 또는 일괄 수정할 필드가 없음
400acl_command_not_allowed명령 패턴에 연산자, 줄바꿈 또는 여러 명령이 포함됨
400acl_exists같은 토큰에 명령/사용자/그룹, 서버, 또는 경로/사용자/그룹/작업이 같은 ACL이 있음
400does_not_exist대상 서비스 토큰이 승인 대기 중이거나 비활성화되었거나 접근 권한 없음. service_token 필드 오류로 반환
400acl_service_token_forbidden토큰을 연결할 수 있는 애플리케이션이 없음. service_token 필드 오류로 반환
400acl_type_not_allowed_for_token토큰에 해당 ACL 유형을 허용하는 scope가 없음
400acl_server_outside_application_scope서버가 애플리케이션에 허용된 범위를 벗어남
401auth_token_missing인증 정보 없음
403permission_denied로그인 세션 대신 개인 API 토큰 또는 서비스 토큰 사용
403workspace_suspended정지된 워크스페이스에 쓰기 요청
404api_not_foundACL이 없거나 조회 권한 없음
405command_acl_movedAlpacon Cloud에서 명령 ACL 쓰기 요청

이 ACL API에는 요금제 제한이 없습니다. 오류 응답 형식은 API 참조, 토큰 관리는 서비스 토큰을 참고하세요.

최종 수정: