- GitLab CI/CD 작업 토큰 보안
- 프로젝트의 작업 토큰 액세스 제어
- 작업 토큰을 사용하여 비공개 프로젝트의 리포지터리 클론
- 프로젝트의 작업 토큰 액세스 제한 (비권장됨)
- 문제 해결
GitLab CI/CD 작업 토큰
Offering: GitLab.com, Self-Managed형, GitLab Dedicated
CI/CD 파이프라인 작업이 실행되기 전에 GitLab은 고유한 토큰을 생성하고 작업에서 CI_JOB_TOKEN
미리 정의된 변수로 사용할 수 있도록 합니다.
이 토큰은 작업이 실행되는 동안에만 유효합니다. 작업이 완료되면 토큰 액세스가 취소되어 더 이상 토큰을 사용할 수 없습니다.
CI/CD 작업 토큰을 사용하여 실행 중인 작업에서 특정 GitLab 기능을 인증합니다.
토큰은 파이프라인을 트리거한 사용자와 동일한 액세스 수준을 받지만 개인 액세스 토큰보다는 적은 리소스에 액세스할 수 있습니다.
사용자는 커밋을 푸시하거나 매뉴얼 작업을 트리거하거나 예약된 파이프라인의 소유자인 등 작업을 실행시킬 수 있습니다.
이 사용자는 해당 리소스에 액세스할 수 있는 필수 권한을 가진 역할을 가져야 합니다.
작업 토큰을 사용하여 GitLab에 인증하여 다른 그룹 또는 프로젝트의 리소스(대상 프로젝트)에 액세스할 수 있습니다.
기본적으로 작업 토큰의 그룹 또는 프로젝트는 대상 프로젝트의 허용 디렉터리에 추가되어야 합니다.
프로젝트가 공개 또는 내부이면 허용 디렉터리에 없어도 일부 기능에 액세스할 수 있습니다.
예를 들어, 프로젝트의 공개 파이프라인에서 artifact를 가져올 수 있습니다.
이 액세스는 또한 제한될 수 있습니다.
기능 | 추가 세부사항 |
---|---|
컨테이너 레지스트리 API | 토큰은 작업 프로젝트의 컨테이너 레지스트리로 제한됩니다. |
컨테이너 레지스트리 |
$CI_REGISTRY_PASSWORD 미리 정의된 변수는 CI/CD 작업 토큰입니다.
|
배포 API |
GET 요청은 기본적으로 공개됩니다.
|
환경 API |
GET 요청은 기본적으로 공개됩니다.
|
작업 artifact API |
GET 요청은 기본적으로 공개됩니다.
|
작업 API | 작업 토큰의 작업을 얻기 위해. |
패키지 레지스트리 | |
패키지 API |
GET 요청은 기본적으로 공개됩니다.
|
파이프라인 트리거 |
token= 매개변수와 함께 다중 프로젝트 파이프라인을 트리거하는 데 사용됩니다.
|
파이프라인 API | 파이프라인 메타데이터를 업데이트하기 위해. |
릴리스 링크 API | |
릴리스 API |
GET 요청은 기본적으로 공개됩니다.
|
Terraform plan |
작업 토큰은 프로젝트의 리소스에 액세스할 수 있지만 불필요한 추가 권한을 부여할 수 있습니다.
보다 세분화된 액세스 권한을 위해 제안이 있습니다.
GitLab CI/CD 작업 토큰 보안
작업 토큰이 노출되면, 해당 CI/CD 작업을 트리거한 사용자의 액세스 가능한 개인 데이터에 잠재적으로 액세스할 수 있습니다.
토큰이 유출되거나 오용되지 않도록 돕기 위해 GitLab은:
- 작업 로그에서 작업 토큰을 마스킹합니다.
- 작업이 실행되는 동안에만 작업 토큰에 대한 권한을 부여합니다.
또한 러너(runner)를 안전하게 구성해야 합니다:
- 기계를 재사용하는 경우 Docker
privileged
모드를 사용하지 않습니다. - 작업이 동일한 머신에서 실행되는 경우
shell
executor를 사용하지 않습니다.
보안이 취약한 GitLab 러너 구성은 다른 작업에서 토큰을 도난당할 수 있는 위험을 증가시킵니다.
프로젝트의 작업 토큰 액세스 제어
특정 그룹이나 프로젝트가 프로젝트의 리소스에 대해 작업 토큰을 사용하여 인증하고 액세스하는 것을 제어할 수 있습니다.
기본적으로 작업 토큰 액세스는 현재 프로젝트에서 파이프라인을 실행하는 CI/CD 작업에만 제한됩니다.
다른 그룹이나 프로젝트가 다른 프로젝트의 파이프라인에서 작업 토큰으로 인증하도록 허용하려면:
- 그룹 또는 프로젝트를 작업 토큰 허용 디렉터리에 추가해야 합니다.
- 작업을 트리거하는 사용자는 현재 프로젝트의 구성원이어야 합니다.
- 사용자는 해당 작업을 수행할 권한을 가져야 합니다.
프로젝트가 공개 또는 내부이면 특정 공개 액세스 가능한 리소스에는 허용 디렉터리에 없는 임의의 프로젝트에서 작업 토큰을 사용하여 액세스할 수 있습니다.
이러한 리소스는 역시 허용 디렉터리에 있는 프로젝트만 액세스할 수 있습니다.
그룹 또는 프로젝트를 작업 토큰 허용 디렉터리에 추가
- GitLab 15.9에서 도입됨. 기본적으로 활성화된
:inbound_ci_scoped_job_token
피처 플래그 뒤에서 배포됨.- GitLab 15.10에서 피처 플래그 제거됨.
- GitLab 16.3에서 이 프로젝트로의 액세스 제한 설정을 이 프로젝트에 대한 액세스로 제한으로 이름 변경함.
- 그룹을 작업 토큰 허용 디렉터리에 추가하는 기능이 GitLab 17.0에서 도입됨.
작업 토큰을 사용하여 인증하고 프로젝트의 리소스에 액세스하는 그룹 또는 프로젝트를 작업 토큰 허용 디렉터리에 추가할 수 있습니다.
기본적으로 모든 프로젝트의 허용 디렉터리에는 해당 프로젝트만 포함됩니다.
예를 들어, 프로젝트 A는 프로젝트 A의 허용 디렉터리에 프로젝트 B를 추가할 수 있습니다.
프로젝트 B(허용된 프로젝트)의 CI/CD 작업은 이제 프로젝트 A에 액세스할 수 있습니다.
그룹 또는 프로젝트를 허용 디렉터리에 추가하는 경우에만 프로젝트 간 액세스가 필요합니다.
전제 조건:
- 현재 프로젝트에서 적어도 관리자 역할이어야 합니다. 허용된 프로젝트가 내부적이거나 비공개인 경우 해당 프로젝트에서 적어도 게스트 역할이어야 합니다.
- 허용 디렉터리에 추가된 그룹 및 프로젝트가 200개를 초과할 수 없습니다.
그룹 또는 프로젝트를 허용 디렉터리에 추가하려면:
- 왼쪽 사이드바에서 검색 또는 찾아가기를 선택하여 프로젝트를 찾습니다.
- 설정 > CI/CD를 선택합니다.
- Token Access를 확장합니다.
-
이 프로젝트로의 액세스 제한 토글이 활성화되어 있는지 확인합니다. 새 프로젝트에서는 기본적으로 활성화됩니다.
이 기능을 비활성화하면 보안 위험성이 발생할 수 있으므로 프로젝트 유지자 또는 소유자는 무조건 이 설정을 활성화 상태로 유지해야 합니다. - 그룹 또는 프로젝트 추가를 선택합니다.
- 허용 디렉터리에 추가하려는 그룹 또는 프로젝트의 경로를 입력하고 프로젝트 추가를 선택합니다.
또한 API를 사용하여 그룹 또는 프로젝트를 허용 디렉터리에 추가할 수 있습니다.
공개 또는 내부 프로젝트에 대한 작업 토큰 범위 제한
- GitLab 16.6에서 도입되었습니다. (소개됨)
허용 디렉터리에 없는 프로젝트는 작업 토큰을 사용하여 공개 또는 내부 프로젝트에 대해 인증하는 데 사용할 수 있습니다:
- 아티팩트 검색.
- 컨테이너 레지스트리 접근.
- 패키지 레지스트리 접근.
- 릴리스, 배포 및 환경 접근.
허용 디렉터리에 있는 프로젝트의 구성원만 이러한 작업에 대한 액세스를 제한하여 이러한 작업에 대한 액세스를 제한할 수 있습니다.
전제 조건:
- 프로젝트의 Maintainer 역할이어야 합니다.
기능을 프로젝트 구성원만 표시되도록 설정하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 일반을 선택합니다.
- 가시성, 프로젝트 기능, 권한을 확장합니다.
- 원하는 기능에 대해 가시성을 프로젝트 구성원만으로 설정합니다.
- 아티팩트 검색 기능은 CI/CD 가시성 설정으로 제어됩니다.
- 변경 사항 저장을 선택합니다.
모든 프로젝트에 대한 프로젝트 액세스 허용
- GitLab 16.3에서 이 프로젝트에 대한 CI_JOB_TOKEN 액세스 허용 설정이 이 프로젝트로의 액세스 제한로 이름이 변경되었습니다.
이 프로젝트로의 액세스 제한 설정을 해제하면 허용 디렉터리이 무시됩니다. 사용자가 파이프라인을 트리거하는 권한이 있는 경우 모든 프로젝트의 작업이 해당 프로젝트에 대한 작업 토큰으로 액세스할 수 있습니다.
이 설정을 테스트하거나 유사한 이유로만 해제해야 하며 가능한 빨리 다시 활성화해야 합니다.
전제 조건:
- 프로젝트의 적어도 Maintainer 역할이어야 합니다.
작업 토큰 범위 허용 디렉터리을 해제하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > CI/CD를 선택합니다.
- 토큰 액세스를 확장합니다.
-
이 프로젝트로의 액세스 제한을 비활성화로 토글합니다.
- 새 프로젝트의 경우 기본적으로 활성화됩니다.
또한 GraphQL (inboundJobTokenScopeEnabled
) 및 REST API로 설정을 활성화하거나 비활성화할 수 있습니다.
작업 토큰을 사용하여 비공개 프로젝트의 리포지터리 클론
작업 토큰을 사용하여 CI/CD 작업에서 비공개 프로젝트의 리포지터리를 인증하고 복제할 수 있습니다. 예를 들어:
git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>
프로젝트의 HTTPS 프로토콜이 그룹, 프로젝트 또는 인스턴스 설정에서 비활성화된 경우에도 작업 토큰을 사용하여 리포지터리를 복제할 수 있습니다. 그러나 작업 토큰으로 리포지터리에 푸시할 수는 없지만 이슈 389060에서 이 동작을 변경하도록 제안되었습니다.
프로젝트의 작업 토큰 액세스 제한 (비권장됨)
프로젝트의 작업 토큰 범위를 제어하여 프로젝트의 작업 토큰으로 액세스할 수 있는 프로젝트의 허용 디렉터리을 만들어 정의할 수 있습니다.
기본적으로 허용 디렉터리에는 현재 프로젝트가 포함됩니다. 다른 프로젝트는 둘 다 액세스 권한이 있는 관리자에 의해 추가 및 삭제할 수 있습니다.
해당 설정이 비활성화된 경우 모든 프로젝트가 허용 디렉터리으로 간주되며 작업 토큰은 사용자의 액세스 권한에만 제한됩니다.
예를 들어 설정이 활성화되면 프로젝트 A
의 파이프라인에서 CI_JOB_TOKEN
범위가 프로젝트 A
로 제한됩니다. 만약 작업이 프로젝트 B
에 대한 API 요청에 토큰을 사용해야 하는 경우 B
를 A
의 허용 디렉터리에 추가해야 합니다.
작업 토큰 범위 구성 (비권장됨)
- GitLab 16.3에서 CI_JOB_TOKEN 액세스 제한 설정이 이 프로젝트로의 액세스 제한로 이름이 변경되었습니다.
전제 조건:
- 토큰의 범위에 추가된 프로젝트 수가 200개를 넘어서는 안 됩니다.
작업 토큰 범위를 구성하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > CI/CD를 선택합니다.
- 토큰 액세스를 확장합니다.
- 이 프로젝트로의 액세스 제한을 활성화로 토글합니다.
- 선택 사항. 토큰의 액세스 범위에 기존 프로젝트를 추가합니다. 프로젝트를 추가하는 사용자는 두 프로젝트 모두에서 Maintainer 역할이어야 합니다.
문제 해결
CI 작업 토큰 실패는 일반적으로 404 Not Found
등의 응답으로 표시됩니다.
-
인증되지 않은 Git 복제:
$ git clone https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.com/fabiopitino/test2.git Cloning into 'test2'... remote: The project you were looking for could not be found or you don't have permission to view it. fatal: repository 'https://gitlab-ci-token:[MASKED]@gitlab.com/<namespace>/<project>.git/' not found
-
인증되지 않은 패키지 다운로드:
$ wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/1234/packages/generic/my_package/0.0.1/file.txt --2021-09-23 11:00:13-- https://gitlab.com/api/v4/projects/1234/packages/generic/my_package/0.0.1/file.txt Resolving gitlab.com (gitlab.com)... 172.65.251.78, 2606:4700:90:0:f22e:fbec:5bed:a9b9 Connecting to gitlab.com (gitlab.com)|172.65.251.78|:443... connected. HTTP request sent, awaiting response... 404 Not Found 2021-09-23 11:00:13 ERROR 404: Not Found.
-
인증되지 않은 API 요청:
$ curl --verbose --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.com/api/v4/projects/1234/trigger/pipeline" < HTTP/2 404 < date: Thu, 23 Sep 2021 11:00:12 GMT {"message":"404 Not Found"} < content-type: application/json
CI/CD 작업 토큰 인증 문제를 해결할 때 주의할 사항:
- GraphQL 예제 뮤테이션을 사용하여 프로젝트당 범위 설정을 토글할 수 있습니다.
-
이 코멘트는 Bash 및 cURL에서 GraphQL을 사용하여 다음을 수행하는 방법을 보여줍니다:
- 수신 토큰 액세스 범위를 활성화합니다.
- 프로젝트 A에서 프로젝트 B에 액세스 권한을 부여하거나 B를 A의 허용 디렉터리에 추가합니다.
- 프로젝트 액세스를 제거합니다.
- 작업이 더 이상 실행 중이 아니거나 삭제되었거나 프로젝트가 삭제되는 중일 경우 CI 작업 토큰이 무효화됩니다.