GitLab 토큰 개요

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

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

개인 액세스 토큰

개인 액세스 토큰은 다음에 사용하여 인증할 수 있습니다:

  • GitLab API.
  • GitLab 리포지터리.
  • GitLab 레지스트리.

개인 액세스 토큰의 범위와 만료일을 제한할 수 있습니다. 기본적으로 그들은 생성 한 사용자의 권한을 상속합니다.

개인 액세스 토큰 API를 사용하여 개인 액세스 토큰을 회전하는 등의 작업을 자동화 할 수 있습니다.

개인 액세스 토큰이 만료 7일 전이 되면 이메일을 받게 됩니다.

OAuth2 토큰

GitLab은 사용자를 대신하여 다른 서비스가 GitLab API에 액세스 할 수 있도록 하기 위해 OAuth2 제공자로 작동할 수 있습니다.

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

루갈 토큰

루갈 토큰은 특정 사용자를 위해 관리자만이 만들 수 있는 특별한 유형의 개인 액세스 토큰입니다. 루갈 토큰을 사용하면 특정 사용자로서 GitLab API, 리포지터리 및 GitLab 레지스트리와 인증을 수행하는 응용 프로그램이나 스크립트를 작성하는 데 도움이 될 수 있습니다.

루갈 토큰의 범위를 제한하고 만료일을 설정할 수 있습니다.

프로젝트 액세스 토큰

프로젝트 액세스 토큰은 프로젝트에 대해 범위가 지정됩니다. 개인 액세스 토큰과 마찬가지로, 이를 사용하여 다음을 인증할 수 있습니다:

  • GitLab API.
  • GitLab 리포지터리.
  • GitLab 레지스트리.

프로젝트 액세스 토큰의 범위 및 만료일을 제한할 수 있습니다. 프로젝트 액세스 토큰을 생성하면 GitLab은 프로젝트용 봇 사용자를 작성합니다. 프로젝트용 봇 사용자는 서비스 계정이며 라이선스가 카운트되지 않습니다.

프로젝트 액세스 토큰 API를 사용하여 프로젝트 액세스 토큰을 회전하는 등의 작업을 자동화 할 수 있습니다.

프로젝트 소유자 및 유지 관리자는 프로젝트 액세스 토큰의 만료 7일 전에 이메일을 받게 됩니다.

그룹 액세스 토큰

그룹 액세스 토큰은 그룹에 대해 범위가 지정됩니다. 개인 액세스 토큰과 마찬가지로, 이를 사용하여 다음을 인증할 수 있습니다:

  • GitLab API.
  • GitLab 리포지터리.
  • GitLab 레지스트리.

그룹 액세스 토큰의 범위 및 만료일을 제한할 수 있습니다. 그룹 액세스 토큰을 생성하면 GitLab은 그룹용 봇 사용자를 작성합니다. 그룹용 봇 사용자는 서비스 계정이며 라이선스가 카운트되지 않습니다.

그룹 액세스 토큰 API를 사용하여 그룹 액세스 토큰을 회전하는 등의 작업을 자동화 할 수 있습니다.

모든 그룹 소유자는 그룹 액세스 토큰의 만료 7일 전에 이메일을 받게 됩니다.

배포 토큰

배포 토큰을 사용하면 사용자 이름과 비밀번호가 없이 프로젝트의(git clone) 다운로드 또는 패키지 및 컨테이너 레지스트리 이미지를 푸시하고 가져올 수 있습니다. 배포 토큰은 GitLab API와 함께 사용할 수 없습니다.

프로젝트 유지 관리자 및 소유자가 배포 토큰을 관리할 수 있습니다.

배포 키

배포 키를 사용하면 SSH 공개 키를 GitLab 인스턴스에 가져와서 귀하의 리포지터리에 대한 읽기 전용 또는 읽기-쓰기 액세스 권한을 부여할 수 있습니다. 배포 키는 GitLab API 또는 레지스트리와 함께 사용할 수 없습니다.

예를 들어 귀하의 CI(Continuous Integration) 서버에 리포지터리를 복제하는 데 유용합니다. 배포 키를 사용하면 가짜 사용자 계정을 설정할 필요가 없습니다.

프로젝트 유지 관리자 및 소유자는 프로젝트 리포지터리에 대해 배포 키를 추가하거나 활성화할 수 있습니다.

::EndTabs::

러너 인증 토큰

GitLab 16.0 이상에서, 러너를 등록할 때 러너 등록 토큰 대신 러너 인증 토큰을 사용할 수 있습니다. 러너 등록 토큰은 폐기되었습니다.

러너와 해당 구성을 작성한 후에는 러너 인증 토큰을 받게 됩니다. 이 러너 인증 토큰을 사용하여 러너를 등록합니다. 러너 인증 토큰은 러너를 구성하는 데 사용되는 config.toml 파일에 로컬로 저장됩니다.

러너는 작업 큐에서 작업을 가져올 때 GitLab과 인증하는 데 러너 인증 토큰을 사용합니다. 러너가 GitLab과 인증한 후에는 작업 토큰을 받게 되며, 이를 사용하여 작업을 실행합니다.

러너 인증 토큰은 러너 머신에 유지됩니다. 다음의 실행 환경에 대한 러너는 작업 토큰만 액세스하며 러너 인증 토큰을 액세스하지 않습니다.

  • Docker Machine
  • Kubernetes
  • VirtualBox
  • Parallels
  • SSH

러너의 파일 시스템에 악의적인 액세스가 허용되면 config.toml 파일과 러너 인증 토큰이 노출될 수 있습니다. 공격자는 러너 인증 토큰을 사용하여 러너를 클론할 수 있습니다.

runners API를 사용하여 러너 인증 토큰을 자동으로 회전 또는 폐기하는 등의 작업을 자동화 할 수 있습니다.

러너 등록 토큰 (폐기됨)

caution
러너 등록 토큰을 전달하는 기능은 폐기되었으며, 특정 구성 인수 지원도 함께 GitLab 18.0에서 제거될 예정입니다. 이 변경 사항은 파괴적인 변경 사항입니다. GitLab은 러너를 등록하는 새로운 GitLab 러너 토큰 아키텍처를 구현했으며, 러너 등록 토큰을 제거합니다.

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

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

CI/CD 작업 토큰

CI/CD 작업 토큰은 작업의 지속 시간 동안에만 유효한 짧은 기간의 토큰입니다. 이 토큰을 사용하여 CI/CD 작업이 제한된 양의 API 엔드포인트에 액세스할 수 있습니다. API 인증은 작업을 트리거하는 사용자의 권한을 사용하여 작동합니다.

이 작업 토큰은 짧은 수명과 제한된 범위로 보안이 유지됩니다. 동일한 머신에서 여러 작업이 실행되면 이 토큰이 유출될 수 있습니다 (셸 러너와 같이). Docker Machine 러너에서는 MaxBuilds=1을 구성하여 러너 머신이 항상 하나의 빌드만 실행하도록하는 것이 권장됩니다. 이는 머신을 프로비저닝하는 데 시간이 소요되므로 성능에 영향을 줄 수 있습니다.

GitLab 클러스터 에이전트 토큰

GitLab Kubernetes 에이전트 등록 시, GitLab은 클러스터 에이전트가 GitLab과 인증하기 위해 액세스 토큰을 생성합니다.

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

  • 에이전트 API를 사용하여 토큰을 폐기합니다.
  • UI를 사용하여 토큰을 재설정합니다.

이러한 방법 모두에는 토큰, 에이전트 및 프로젝트 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 콘솔에서 직접 토큰을 폐기할 수도 있습니다:

# 폐기 서비스와 함께 토큰 폐기하기, 감사 이벤트 생성 포함
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!

::EndTabs::

기타 토큰

피드 토큰

각 사용자에게 만료되지 않는 장기적인 피드 토큰이 제공됩니다. 이 토큰을 사용하여 다음을 인증할 수 있습니다.

  • RSS 리더가 사용자별 RSS 피드를 로드합니다.
  • 캘린더 애플리케이션이 사용자별 캘린더를 로드합니다.

이 토큰으로는 다른 데이터에 액세스할 수 없습니다.

사용자별 피드 토큰은 모든 피드에 사용할 수 있지만, 피드 및 캘린더 URL은 하나의 피드에만 유효한 토큰으로 생성됩니다.

누군가 귀하의 토큰을 소유하고 있다면, 신뢰도 있는 활동과 이슈 RSS 피드 또는 캘린더 피드를 읽을 수 있습니다. 그런 경우, 토큰을 재설정하세요.

피드 토큰 비활성화

전제 조건:

  • 관리자여야 합니다.
  1. 왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
  2. 설정 > 일반을 선택합니다.
  3. 가시성 및 액세스 제어를 확장합니다.
  4. 피드 토큰 아래에서 피드 토큰 비활성화 확인란을 선택한 후 변경 사항 저장을 선택합니다.

수신 이메일 토큰

각 사용자에게 만료되지 않는 장기적인 수신 이메일 토큰이 제공됩니다. 이 토큰을 사용하여 사용자가 이메일로 새 이슈를 생성할 수 있으며, 해당 사용자의 개인 프로젝트별 이메일 주소에 포함됩니다. 이 토큰으로는 다른 데이터에 액세스할 수 없습니다. 귀하의 토큰을 가진 사람은 귀하인 것처럼 이슈를 만들거나 Merge Request할 수 있습니다. 그런 경우, 토큰을 재설정하세요.

사용 가능한 스코프

이 표는 토큰당 사용 가능한 스코프를 보여줍니다. 스코프는 토큰 생성 시 더욱 제한될 수 있습니다.

토큰 이름 API 액세스 레지스트리 액세스 리포지터리 액세스
개인 액세스 토큰
OAuth2 토큰 아니요
표시용 토큰
프로젝트 액세스 토큰 예(1) 예(1) 예(1)
그룹 액세스 토큰 예(2) 예(2) 예(2)
배포 토큰 아니요
배포 키 아니요 아니요
Runner 등록 토큰 아니요 아니요 ✴️(3)
Runner 인증 토큰 아니요 아니요 ✴️(3)
작업 토큰 ✴️(4) 아니요
  1. 특정 엔드포인트로 제한됨.
  2. 특정 그룹으로 제한됨.
  3. Runner 등록 및 인증 토큰은 리포지터리에 직접 액세스 권한을 제공하지는 않지만, 리포지터리에 액세스할 수 있는 작업을 실행할 수 있는 새 Runner를 등록하고 인증하는 데 사용할 수 있습니다.
  4. 특정 endpoinst로 제한됨.

토큰 접두어

다음 표는 각 유형의 토큰에 대한 접두어를 보여줍니다.

토큰 이름 접두어
개인 액세스 토큰 glpat-
OAuth 애플리케이션 비밀번호 gloas-
표시용 토큰 glpat-
프로젝트 액세스 토큰 glpat-
그룹 액세스 토큰 glpat-
배포 토큰 gldt- (Added in GitLab 16.7)
Runner 인증 토큰 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-

보안 고려 사항

  1. 액세스 토큰을 비밀번호처럼 취급하고 안전하게 보관하세요.
  2. 스코프가 지정된 토큰을 만들 때는, 토큰이 노출되었을 때의 영향을 줄이기 위해 가능한 한 가장 제한적인 스코프를 사용하도록 고려하세요.
  3. 토큰을 만들 때 작업이 완료되면 만료되는 토큰을 설정하는 것을 고려하세요. 예를 들어 일회성 가져오기를 수행하는 경우, 토큰을 몇 시간 또는 하루 후에 만료되도록 설정하세요. 이렇게 하면 토큰이 노출되어도 쓸모 없어지기 때문에 영향을 줄일 수 있습니다.
  4. 프로젝트를 소개하기 위해 데모 환경을 설정하고 해당 프로젝트에 대해 비디오를 녹화하거나 해당 프로젝트를 기술한 블로그 글을 작성하는 경우, 민감한 시크릿(예: 개인 액세스 토큰(PAT), 피드 토큰 또는 트리거 토큰)이 누설되지 않도록 항상 주의하십시오. 데모를 완료한 후에는 해당 데모 중에 생성된 모든 비밀을 폐기해야 합니다. 자세한 내용은 PAT를 폐기를 참조하십시오.
  5. URL에 액세스 토큰을 추가하는 것은 보안 위험입니다, 특히 복제 또는 리모트 추가할 때 Git이 URL을 평문으로 .git/config 파일에 기록합니다. URL은 또한 대부분의 프록시 및 애플리케이션 서버에서 로깅되므로 이러한 자격 증명은 시스템 관리자에게 표시됩니다. 대신 프라이빗 토큰 헤더와 같이 헤더를 사용하여 API 호출에 액세스 토큰을 전달하세요.
  6. Git 자격 증명 리포지터리를 사용하여 토큰을 저장할 수도 있습니다.
  7. 다음을 수행하지 마십시오:
    • 프로젝트에서 평문으로 토큰을 저장합니다.
    • 코드, 콘솔 명령 또는 로그 출력을 이슈, MR 설명 또는 코멘트에 붙일 때 토큰을 포함시킵니다.

    CI에서 외부 시크릿 사용 등의 접근 방식을 고려하세요.

  8. 자격 증명을 콘솔 로그나 아티팩트에 기록하지 마십시오. CI/CD 변수를 보호하고 마스킹하는 것을 고려하세요.
  9. 주기적으로 활성 액세스 토큰을 모두 검토하고 더 이상 필요하지 않은 것은 폐기하세요. 이에는 다음이 포함됩니다:
    • 개인, 프로젝트 및 그룹 액세스 토큰.
    • 피드 토큰.
    • 트리거 토큰.
    • Runner 등록 토큰.
    • 기타 민감한 시크릿 등.