API 접근 토큰
API 접근 토큰은 CI/CD 파이프라인, 자동화 스크립트 및 기타 연동을 위해 Alpacon API에 프로그래밍 방식으로 접근할 수 있게 합니다. 각 토큰은 접근 범위를 통해 허용되는 리소스와 액션을 제한할 수 있으며, ACL 규칙을 통해 명령어, 파일 작업, 서버 접근을 추가로 제한할 수 있습니다.
해당 토큰만으로 Alpacon API에 로그인 세션 없이도 접근할 수 있으므로 절대 외부에 공유하지 마세요.
토큰 목록
각 토큰의 이름, 접근 범위 수, 유효 기간, 마지막 업데이트를 확인할 수 있습니다.
토큰 생성
- 추가 버튼을 클릭합니다.
- 토큰 이름을 설정합니다.
- 만료일을 설정합니다 (7일, 30일, 60일, 90일, 1년, 사용자 지정, 만료 없음).
- 접근 범위를 선택하여 토큰이 접근할 수 있는 리소스와 액션을 정의합니다.
- 생성을 클릭합니다.
- 생성된 토큰 키가 상세 화면에 표시됩니다. 반드시 복사하여 안전한 위치에 저장하세요—페이지를 떠나면 다시 조회할 수 없습니다.
접근 범위
접근 범위는 API 접근 토큰이 수행할 수 있는 리소스와 액션을 정의합니다. 형식은 {resource}:{action}입니다.
사용 가능한 리소스
리소스는 카테고리별로 그룹화되어 있습니다. 접근 범위 선택 UI에서 리소스를 선택하면 사용 가능한 액션을 확인할 수 있습니다.
| 카테고리 | 리소스 |
|---|---|
| 서버 | server, server_acl |
| 세션 | session, ftp_session, tunnel_session, backhaul_session, userchannel |
| 명령어 | command, command_acl |
| 파일 | downloaded_file, uploaded_file, file_acl |
| IAM | user, group, membership |
| 모니터링 | metric, event, event_session, event_subscription, alert, alert_rule, activity, proc |
| 보안 그룹 | security_group, security_group_assignment, security_group_snapshot, firewall_chain, firewall_rule |
| 네트워크 | access_policy, access_rule, proxy_server, proxy_profile, network, subnet, pool, interface, host |
| DNS | dns_server, dns_view, domain, domain_group, record, zone |
| DHCP | dhcp_server, dhcp_session, lease |
| PKI | authority, certificate, sign_request, revoke_request |
| 등록 | registration_method, registration_token |
| 워크스페이스 | workspace, preferences, webhook, note |
| 패키지 | package, package_entry |
| 승인 | approval_request |
와일드카드
| 접근 범위 | 의미 |
|---|---|
* | 모든 리소스의 모든 액션 (전체 접근) |
{resource}:* | 특정 리소스의 모든 액션 |
접근 범위 선택
접근 범위는 2단계로 선택합니다: 리소스를 선택한 후 해당 리소스의 액션을 선택합니다. 전체 접근을 선택하면 와일드카드 * 접근 범위가 부여됩니다.
선택된 접근 범위는 액션 유형별로 색상이 구분된 태그로 표시됩니다.
필요에 맞는 최소한의 접근 범위만 선택하세요.
토큰 상세
목록에서 토큰을 클릭하면 상세 화면으로 이동합니다.
토큰 관리
- 우측 상단의 토글 버튼을 통해 토큰을 활성화 또는 비활성화할 수 있습니다.
- 다음과 같은 항목에 대해 관리합니다:
| 기능 | 설명 |
|---|---|
| 토큰 업데이트 | 토큰의 이름, 만료일, 접근 범위를 수정합니다. |
| 토큰 삭제 | 토큰을 영구적으로 삭제합니다. |
| 토큰 복제 | 동일한 접근 범위, ACL 규칙, 만료일로 토큰을 복제합니다. |
| 허용된 명령어 | 토큰으로 실행 가능한 명령어를 제한합니다. |
| 허용된 파일 작업 | 토큰으로 수행 가능한 파일 작업을 제한합니다. |
| 허용된 서버 | 토큰으로 접근 가능한 서버를 제한합니다. |
토큰 복제
복제를 클릭하면 토큰의 복사본이 생성됩니다. 복제된 토큰은 원본의 접근 범위, ACL 규칙, 만료일을 상속합니다. 새 토큰 이름에는 “(copy)” 접미사가 추가됩니다.
ACL 규칙
ACL(Access Control List) 규칙은 접근 범위 수준의 권한을 넘어 토큰이 수행할 수 있는 작업을 세밀하게 제어합니다. 각 ACL 유형은 토큰 사용의 특정 측면을 제한합니다.
중요: Command/File/Server ACL은 해당 기능에 필요한 접근 범위가 토큰에 먼저 부여된 경우에만 의미가 있습니다. 관련 접근 범위가 없다면, ACL에 항목이 등록되어 있어도 해당 기능에는 접근할 수 없습니다. 반대로, 관련 접근 범위는 있지만 ACL 유형에 항목이 등록되지 않은 경우 그 기능에 대한 접근이 허용되지 않습니다. 접근을 허용하려면, 필요한 접근 범위를 부여한 뒤 해당 ACL 유형에 최소 1개 이상의 항목을 등록하세요.
허용된 명령어
허용된 명령어는 해당 토큰으로 실행 가능한 명령어를 제어합니다.
- 명령어를 등록하지 않은 경우: 명령어 실행 불가
- 명령어를 1개라도 등록한 경우: 등록된 명령어만 실행 가능
각 명령어 항목은 다음 필드로 구성됩니다:
| 필드 | 설명 |
|---|---|
| 명령어 | 허용할 명령어. 와일드카드(*) 지원. |
| 유저명 | 명령어를 실행할 사용자. *는 모든 사용자, 빈값은 토큰 소유자. |
| 그룹명 | 명령어 실행의 그룹 컨텍스트. *는 모든 그룹, 빈값은 제한 없음. |
허용된 파일 작업
허용된 파일 작업은 해당 토큰으로 수행 가능한 파일 전송 작업(업로드/다운로드)을 제어합니다.
- 파일 작업을 등록하지 않은 경우: 파일 작업 수행 불가
- 파일 작업을 1개라도 등록한 경우: 등록된 파일 작업만 수행 가능
각 파일 작업 항목은 다음 필드로 구성됩니다:
| 필드 | 설명 |
|---|---|
| 경로 | 허용할 파일 경로. 와일드카드(*) 지원. |
| 작업 | 작업 유형: 업로드, 다운로드, 또는 전체. |
| 유저명 | 파일 작업을 수행할 사용자. *는 모든 사용자, 빈값은 토큰 소유자. |
| 그룹명 | 파일 작업의 그룹 컨텍스트. *는 모든 그룹, 빈값은 제한 없음. |
허용된 서버
허용된 서버는 해당 토큰으로 접근 가능한 서버를 제어합니다.
- 서버를 등록하지 않은 경우: 서버 접근 불가
- 서버를 1개라도 등록한 경우: 등록된 서버만 접근 가능
서버 목록에서 선택하여 추가합니다.
보안 모범 사례
- 최소 권한 원칙: 토큰의 용도에 필요한 접근 범위만 부여하세요.
- 정기적인 토큰 교체: 만료일을 설정하고 만료 전에 새 토큰을 생성하세요.
- ACL 규칙 설정: 허용된 명령어, 파일 작업, 서버를 제한하여 위험을 최소화하세요.
- 토큰 안전 보관: CI/CD 플랫폼의 암호화된 시크릿에 토큰을 저장하세요.
- 미사용 토큰 정리: 더 이상 필요하지 않은 토큰은 비활성화하거나 삭제하세요.