개인 접근 토큰
OAuth 2.0 토큰
에임퍼소네이션 토큰
프로젝트 접근 토큰
그룹 접근 토큰
배포 토큰
배포 키
러너 인증 토큰
러너 등록 토큰 (더 이상 사용되지 않음)
CI/CD 작업 토큰
GitLab 클러스터 에이전트 토큰
기타 토큰
- 피드 토큰
  - 피드 토큰 비활성화
- 인바운드 이메일 토큰
사용 가능한 범위
토큰 접두사
보안 고려사항

GitLab 토큰 개요

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이 문서는 GitLab에서 사용되는 토큰, 그 목적 및 해당되는 경우 보안 지침을 나열합니다.

개인 접근 토큰

개인 접근 토큰을 생성하여 다음을 인증할 수 있습니다:

GitLab API.
GitLab 리포지토리.
GitLab 레지스트리.

개인 접근 토큰의 범위와 만료 날짜를 제한할 수 있습니다. 기본적으로 토큰은 생성한 사용자의 권한을 상속받습니다.

개인 접근 토큰 API를 사용하여 개인 접근 토큰 회전과 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

토큰의 만료일까지 7일 이하가 남으면 이메일을 받습니다.

OAuth 2.0 토큰

GitLab은 OAuth 2.0 제공자로 작동하여 다른 서비스가 사용자를 대신하여 GitLab API에 접근할 수 있도록 합니다.

OAuth 2.0 토큰의 범위와 수명을 제한할 수 있습니다.

에임퍼소네이션 토큰

에임퍼소네이션 토큰은 특별한 유형의 개인 접근 토큰입니다. 특정 사용자를 위해 관리자만 생성할 수 있습니다. 에임퍼소네이션 토큰은 GitLab API, 리포지토리 및 GitLab 레지스트리에 특정 사용자로 인증하는 애플리케이션이나 스크립트를 구축하는 데 도움이 됩니다.

에임퍼소네이션 토큰에 대한 범위를 제한하고 만료 날짜를 설정할 수 있습니다.

프로젝트 접근 토큰

프로젝트 접근 토큰은 프로젝트에 한정됩니다. 개인 접근 토큰과 마찬가지로 다음을 인증하는 데 사용할 수 있습니다:

GitLab API.
GitLab 리포지토리.
GitLab 레지스트리.

프로젝트 접근 토큰의 범위와 만료 날짜를 제한할 수 있습니다. 프로젝트 접근 토큰을 생성하면 GitLab은 프로젝트용 봇 사용자를 생성합니다. 프로젝트용 봇 사용자는 서비스 계정이며 라이센스 있는 좌석으로 계산되지 않습니다.

프로젝트 접근 토큰 API를 사용하여 프로젝트 접근 토큰 회전과 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

최소 유지 관리 역할을 가진 프로젝트의 직접 구성원은 프로젝트 접근 토큰의 만료일까지 7일 이하가 남으면 이메일을 받습니다. 상속된 구성원은 이메일을 받지 않습니다.

그룹 접근 토큰

그룹 접근 토큰은 그룹에 한정됩니다. 개인 접근 토큰과 마찬가지로 다음을 인증하는 데 사용할 수 있습니다:

GitLab API.
GitLab 리포지토리.
GitLab 레지스트리.

그룹 접근 토큰의 범위와 만료 날짜를 제한할 수 있습니다. 그룹 접근 토큰을 생성하면 GitLab은 그룹용 봇 사용자를 생성합니다. 그룹용 봇 사용자는 서비스 계정이며 라이센스 있는 좌석으로 계산되지 않습니다.

그룹 접근 토큰 API를 사용하여 그룹 접근 토큰 회전과 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

소유자 역할을 가진 그룹의 직접 구성원은 그룹 접근 토큰의 만료일까지 7일 이하가 남으면 이메일을 받습니다. 상속된 구성원은 이메일을 받지 않습니다.

배포 토큰

배포 토큰은 사용자가 없고 비밀번호 없이 패키지 및 컨테이너 레지스트리 이미지를 클론, 푸시 및 풀 할 수 있게 해줍니다. 배포 토큰은 GitLab API와 함께 사용할 수 없습니다.

배포 토큰을 관리하려면 최소한 Maintainer 역할을 가진 프로젝트의 구성원이 되어야 합니다.

배포 키

배포 키는 SSH 공개 키를 당신의 GitLab 인스턴스에 가져와서 저장소에 대한 읽기 전용 또는 읽기 쓰기 액세스를 허용합니다. 배포 키는 GitLab API나 레지스트리와 함께 사용할 수 없습니다.

배포 키를 사용하여 가짜 사용자 계정을 설정하지 않고도 지속적 통합 서버에 리포지토리를 클론할 수 있습니다.

프로젝트에 대해 배포 키를 추가하거나 활성화하려면 최소한 Maintainer 역할을 가져야 합니다.

러너 인증 토큰

GitLab 16.0 이상에서는 러너를 등록하기 위해 러너 등록 토큰 대신 러너 인증 토큰을 사용할 수 있습니다. 러너 등록 토큰은 더 이상 사용되지 않음 상태입니다.

러너와 그 구성 설정을 만든 후, 러너를 등록하는 데 사용할 러너 인증 토큰을 받습니다. 러너 인증 토큰은 config.toml 파일에 로컬로 저장되며, 이 파일을 사용하여 러너를 구성합니다.

러너는 작업 큐에서 작업을 가져올 때 GitLab에 인증하기 위해 러너 인증 토큰을 사용합니다. 러너가 GitLab에 인증한 후, 러너는 작업을 실행하는 데 사용할 수 있는 작업 토큰을 받습니다.

러너 인증 토큰은 러너 머신에 남아 있습니다. 다음 실행기에 대한 실행 환경은 작업 토큰에만 액세스할 수 있으며 러너 인증 토큰에는 액세스할 수 없습니다:

Docker Machine
Kubernetes
VirtualBox
Parallels
SSH

악의적인 접근이 러너의 파일 시스템에 있을 경우 config.toml 파일과 러너 인증 토큰을 노출시킬 수 있습니다. 공격자는 러너 인증 토큰을 사용하여 러너를 클론할 수 있습니다.

러너 API를 사용하여 러너 인증 토큰을 회전하거나 철회할 수 있습니다.

러너 등록 토큰 (더 이상 사용되지 않음)

경고: 러너 등록 토큰을 전달하는 기능은 더 이상 사용되지 않음 상태이며, 특정 구성 인수에 대한 지원과 함께 GitLab 18.0에서 제거될 예정입니다. 이 변경은 중단된 변경 사항입니다. GitLab은 새로운 GitLab 러너 토큰 아키텍처를 구현하였으며, 이는 러너 등록을 위한 새로운 방법을 도입하고 러너 등록 토큰을 제거합니다.

러너 등록 토큰은 러너를 등록하는 데 사용됩니다. 그룹 또는 프로젝트 소유자 또는 인스턴스 관리자가 GitLab 사용자 인터페이스를 통해 이를 얻을 수 있습니다. 등록 토큰은 러너 등록으로 제한되며 추가적인 범위가 없습니다.

러너 등록 토큰을 사용하여 프로젝트 또는 그룹에서 작업을 실행하는 러너를 추가할 수 있습니다. 러너는 프로젝트의 코드에 접근할 수 있으므로, 프로젝트 또는 그룹에 권한을 부여할 때 주의해야 합니다.

CI/CD 작업 토큰

CI/CD 작업 토큰은 작업 기간 동안만 유효한 짧은 수명의 토큰입니다. 이 토큰은 CI/CD 작업이 제한된 수의 API 엔드포인트에 액세스할 수 있게 해줍니다. API 인증은 작업을 트리거하는 사용자의 승인을 통해 작업 토큰을 사용합니다.

작업 토큰은 짧은 수명과 제한된 범위로 보호됩니다. 이 토큰은 동일한 머신에서 여러 작업이 실행되는 경우 유출될 수 있습니다 (예: 쉘 러너 사용 시). Docker Machine 러너에서는 MaxBuilds=1 를 구성하여 러너 머신이 하나의 빌드만 실행하고 그 후에 파괴되도록 해야 합니다. 프로비저닝에는 시간이 걸리므로, 이 구성이 성능에 영향을 미칠 수 있습니다.

GitLab 클러스터 에이전트 토큰

GitLab 에이전트를 Kubernetes에 등록하면 GitLab은 클러스터 에이전트를 GitLab과 인증하는 액세스 토큰을 생성합니다.

이 클러스터 에이전트 토큰을 취소하려면 다음 방법 중 하나를 사용할 수 있습니다:

agents API를 사용하여 토큰 취소.
토큰 재설정.

두 방법 모두 토큰, 에이전트 및 프로젝트 ID를 알고 있어야 합니다. 이 정보를 찾으려면 Rails 콘솔을 사용하세요:

# 토큰 ID 찾기
Clusters::AgentToken.find_by_token('glagent-xxx').id

# 에이전트 ID 찾기
Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
=> 1234

# 프로젝트 ID 찾기
Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
=> 12345

Rails 콘솔에서 직접 토큰을 취소할 수도 있습니다:

# RevokeService로 토큰 취소, 감사 이벤트 생성 포함
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# 수동으로 토큰 취소, 감사 이벤트 생성하지 않음
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

기타 토큰

피드 토큰

각 사용자에게는 만료되지 않는 장기 사용 피드 토큰이 있습니다.

다음과 같이 인증하는 데 이 토큰을 사용하세요:

RSS 리더기, 개인화된 RSS 피드를 불러오기 위해.
캘린더 애플리케이션, 개인화된 캘린더를 불러오기 위해.

이 토큰을 사용하여 다른 데이터에 접근할 수는 없습니다.

모든 피드에 대해 사용자 범위 피드 토큰을 사용할 수 있습니다. 그러나 피드 및 캘린더 URL은 하나의 피드에만 유효한 다른 토큰으로 생성됩니다.

귀하의 토큰을 가진 사람은 비밀 문제를 포함하여 귀하의 피드 활동을 마치 귀하처럼 볼 수 있습니다. 토큰이 유출되었다고 생각되면 토큰을 즉시 재설정하세요.

피드 토큰 비활성화

전제 조건:

관리자가 되어야 합니다.

왼쪽 사이드바에서 하단에 있는 Admin을 선택합니다.
Settings > General을 선택합니다.
Visibility and access controls를 확장합니다.
Feed token 아래에서 Disable feed token 체크박스를 선택한 후 Save changes를 선택합니다.

인바운드 이메일 토큰

각 사용자에게는 만료되지 않는 인바운드 이메일 토큰이 있습니다. 이 토큰은 개인 프로젝트와 관련된 이메일 주소에 포함됩니다.

이 토큰을 사용하여 이메일로 새 문제 생성합니다.

이 토큰을 사용하여 다른 데이터에 접근할 수는 없습니다. 귀하의 토큰을 가진 사람은 마치 귀하처럼 문제와 병합 요청을 생성할 수 있습니다. 토큰이 유출되었다고 생각되면 즉시 토큰을 재설정하세요.

사용 가능한 범위

이 표는 각 토큰의 기본 범위를 보여줍니다. 일부 토큰에 대해서는 토큰을 생성할 때 범위를 더 제한할 수 있습니다.

토큰 이름	API 액세스	레지스트리 액세스	저장소 액세스
개인 액세스 토큰	예	예	예
OAuth 2.0 토큰	예	아니요	예
대리인 토큰	예	예	예
프로젝트 액세스 토큰	예¹	예¹	예¹
그룹 액세스 토큰	예²	예²	예²
배포 토큰	아니요	예	예
배포 키	아니요	아니요	예
러너 등록 토큰	아니요	아니요	제한적³
러너 인증 토큰	아니요	아니요	제한적³
작업 토큰	제한적⁴	아니요	예

각주:

한 프로젝트로 제한됨.
한 그룹으로 제한됨.
러너 등록 및 인증 토큰은 저장소에 직접 접근할 수 없지만, 작업을 수행할 수 있는 새 러너를 등록하고 인증하는 데 사용할 수 있습니다.
특정 엔드포인트에서만.

토큰 접두사

다음 표는 각 유형의 토큰 접두사를 보여줍니다.

토큰 이름	접두사
개인 액세스 토큰	`glpat-`
OAuth 애플리케이션 비밀	`gloas-`
가장한 토큰	`glpat-`
프로젝트 액세스 토큰	`glpat-`
그룹 액세스 토큰	`glpat-`
배포 토큰	`gldt-` (GitLab 16.7에 추가)
러너 인증 토큰	`glrt-`
CI/CD 작업 토큰	`glcbt-` • ([GitLab 16.8에서 `prefix_ci_build_tokens`라는 기능 플래그 뒤에 도입됨. 기본적으로 비활성화됨.) • (GitLab 16.9에서 일반 사용 가능. 기능 플래그 `prefix_ci_build_tokens` 제거됨.)
트리거 토큰	`glptt-`
피드 토큰	`glft-`
수신 메일 토큰	`glimt-`
Kubernetes용 GitLab 에이전트 토큰	`glagent-`
GitLab 세션 쿠키	`_gitlab_session=`
SCIM 토큰	`glsoat-` • ([GitLab 16.8에서 `prefix_scim_tokens`라는 기능 플래그 뒤에 도입됨. 기본적으로 비활성화됨.) • (GitLab 16.9에서 일반 사용 가능. 기능 플래그 `prefix_scim_tokens` 제거됨.)
기능 플래그 클라이언트 토큰	`glffct-`

보안 고려사항

토큰을 안전하게 유지하려면:

액세스 토큰을 비밀번호처럼 취급하고 안전하게 보관하세요.
범위가 제한된 토큰을 생성할 때는 토큰이 우연히 유출되는 영향을 줄이기 위해 가능한 한 제한된 범위를 사용하는 것을 고려하세요.
토큰을 생성할 때는 작업이 완료되면 만료되는 토큰을 설정하는 것을 고려하세요. 예를 들어, 일회성 가져오기를 수행해야 하는 경우, 몇 시간 후에 만료되도록 토큰을 설정하세요.
작업 중인 프로젝트를 보여주기 위해 데모 환경을 설정하고, 해당 프로젝트에 대한 비디오를 녹화하거나 블로그 게시물을 작성할 경우, 비밀이 우연히 유출되지 않도록 주의하세요.
데모가 끝난 후에는 데모 중에 생성된 모든 비밀을 철회하세요.
URL에 액세스 토큰을 추가하는 것은 보안 위험이 있으며, 특히 복제하거나 원격을 추가할 때, Git은 URL을 일반 텍스트로 .git/config 파일에 기록합니다.
URL은 종종 프록시 및 애플리케이션 서버에 기록되어 시스템 관리자에게 해당 자격 증명이 유출됩니다. 대신, Private-Token과 같은 헤더가 있는 API 호출에 액세스 토큰을 전달하세요.
Git 자격 증명 저장소를 사용하여 토큰을 저장할 수 있습니다.
정기적으로 모든 유형의 활성 액세스 토큰을 검토하고 필요하지 않은 토큰은 철회하세요.

하지 말아야 할 것들:

프로젝트에서 토큰을 일반 텍스트로 저장하지 마세요. 토큰이 GitLab CI/CD의 외부 비밀인 경우, CI에서 외부 비밀을 사용하는 방법 권장 사항을 검토하세요.
코드, 콘솔 명령 또는 로그 출력을 문제, MR 설명 또는 댓글에 붙여넣을 때는 토큰을 포함하지 마세요.
콘솔 로그나 아티팩트에 자격 증명을 기록하지 마세요. 자격 증명을 보호하고 마스킹하는 것을 고려하세요.

GitLab 토큰 개요

개인 접근 토큰

OAuth 2.0 토큰

에임퍼소네이션 토큰

프로젝트 접근 토큰

그룹 접근 토큰

배포 토큰

배포 키

러너 인증 토큰

러너 등록 토큰 (더 이상 사용되지 않음)

CI/CD 작업 토큰

GitLab 클러스터 에이전트 토큰

기타 토큰

피드 토큰

피드 토큰 비활성화

인바운드 이메일 토큰

사용 가능한 범위

토큰 접두사

보안 고려사항

도움말

기능 사용 가능성과 제품 평가판

도움받기