서비스 토큰

서비스 토큰은 Application이 Alpacon API에 인증할 수 있도록 발급되는 자격 증명입니다. 토큰은 범위가 제한되고 IP·요청 수·시간으로 추가 제한할 수 있으며, 모든 변경이 감사 로그에 기록됩니다.

토큰은 Application의 자격 증명 탭에서 생성하고 관리합니다.

토큰 발급

토큰 생성 시 다음을 설정합니다.

이름: 식별할 짧은 이름.
설명(선택): 토큰의 용도.
접근 범위(scopes): 토큰에 부여할 권한(최소 하나 선택). 각 항목이 무엇을 여는지는 접근 범위 레퍼런스에 정리돼 있습니다.
만료: 프리셋(1주, 1개월, 3개월, 6개월, 1년)이나 사용자 지정 날짜, 또는 만료 없음.
사유: 선택한 접근 범위가 Medium 또는 High 위험도인 경우 필수입니다(위험도와 승인 참고).

고급 설정에서 토큰을 추가로 제한할 수 있습니다.

IP 화이트리스트: 특정 IP 주소나 CIDR 범위로 제한.
요청 제한(rate limit): 단위 시간당 요청 수 제한(예: 1000/hour).
시간 제한: 특정 시간대(UTC)와 선택한 요일에만 접근 허용.

1회성 키

생성 후 토큰 키는 한 번만 표시됩니다. 안전하게 복사·보관하세요. 창을 닫으면 다시 표시되지 않습니다. 분실하면 토큰을 교체해 새 키를 발급해야 합니다.

위험도와 승인

각 토큰에는 접근 범위에 따라 위험도(낮음, 중간, 높음)가 자동으로 부여됩니다. Medium·High 위험도 범위를 선택하면 사유가 필요하며, 이러한 토큰 발급은 적용되기 전에 관리자 승인이 필요할 수 있습니다. 요청이 대기 중이면 요청 관리(Approvals)에 표시됩니다.

토큰 상세

서비스 토큰 상세 페이지에는 다음 탭이 있습니다.

개요: 토큰 메타데이터(Application, 접근 범위, 위험도, 상태, 만료, 사용량)와 생성·수정·교체·비활성화·긴급 액세스 등 모든 이벤트의 변경 이력 타임라인.
ACL: 이 토큰에 허용된 서버, 명령, 파일 작업. 명령 항목이 어떻게 매칭되는지는 명령 패턴과 sudo를 참고하세요.
보안: IP 화이트리스트, 요청 제한, 시간 제한, 긴급 액세스(아래 참고). 이곳의 변경은 사유가 필요하며 감사됩니다.
활동: 변경 감사 로그(관리자 전용).

권한이 필요한 명령

서비스 토큰도 sudo가 필요한 명령을 실행할 수 있습니다. 조건은 두 가지입니다.

먼저 토큰의 허용된 명령 항목에 sudo 접두어가 들어가야 합니다. 항목은 root로 실행될 명령이 아니라 제출한 명령줄과 비교되기 때문입니다. 권한 상승 자체는 명령의 위험도 평가로 결정되어 Low, Medium, High는 허용되고 Critical은 거부됩니다. 서비스 토큰은 사람의 승인을 기다리지 않으며 sudo 정책도 적용되지 않습니다. 자동으로 허용된 권한 상승은 모두 Sudo에 애플리케이션 이름으로 기록됩니다.

항목을 작성하기 전에 명령 패턴과 sudo를 읽어 보세요. sudo * 항목은 토큰에 제한 없는 root 권한을 부여합니다.

Break-glass (긴급 액세스)

보안 탭의 위험 영역에서 긴급 액세스는 사고 상황에 토큰의 IP 제한과 시간 제한을 임시로 해제합니다. 요청 제한과 접근 제어(ACL) 규칙은 그대로 적용됩니다. 긴급 액세스는 Superuser가 사용할 수 있습니다.

활성화: 기간(1~8시간)과 사유를 지정합니다. 해당 시간 동안만 제한이 해제됩니다.
비활성화: 토큰의 정상 제한을 즉시 복구합니다.

활성화와 비활성화 모두 감사 로그에 기록됩니다.