• 개인 액세스 토큰
• OAuth2 토큰
• 사용자 변장 토큰
• 프로젝트 액세스 토큰
• 그룹 액세스 토큰
• 배포 토큰
• 배포 키
• 러너 인증 토큰
• 러너 등록 토큰 (폐기됨)
• CI/CD 작업 토큰
• GitLab 클러스터 에이전트 토큰
• 기타 토큰
  • 피드 토큰
    • 피드 토큰 비활성화
  • 수신 이메일 토큰
• 사용 가능한 범위
• 토큰 접두사
  • GitLab 토큰
  • 외부 시스템 토큰
• 보안 고려 사항

GitLab 토큰 개요

이 문서는 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) 서버에서 리포지터리를 복제하는 경우 유용합니다. 배포 키를 사용하면 가짜 사용자 계정을 설정할 필요가 없습니다.

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

러너 인증 토큰

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

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

러너는 작업 대기열에서 작업을 가져올 때 GitLab과 인증하기 위해 러너 인증 토큰을 사용합니다. 러너가 GitLab과 인증한 후에는 작업 토큰을 받아 작업을 실행합니다.

러너 인증 토큰은 러너 머신에 유지됩니다. 다음 실행기의 실행 환경은 작업 토큰만 갖고 있으며 러너 인증 토큰은 갖고 있지 않습니다:

• Docker Machine
• Kubernetes
• VirtualBox
• Parallels
• SSH

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

프로그래밍 방식으로 러너 인증 토큰을 회전하거나 취소할 수 있도록 runners API를 사용할 수 있습니다.

러너 등록 토큰 (폐기됨)

러너 등록 토큰을 사용하여 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 콘솔에서 토큰을 직접 폐기할 수도 있습니다:

# 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은 하나의 피드에 대해서만 유효한 다른 토큰으로 생성됩니다.

누군가가 여러분의 토큰을 가지고 있다면, 활동 및 이슈 RSS 피드 또는 캘린더 피드를 읽을 수 있습니다. 그런 경우, 토큰을 재설정하세요.

피드 토큰 비활성화

사전 요구 사항:

• 관리자 권한이 있어야 합니다.

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

수신 이메일 토큰

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

사용 가능한 범위

이 표는 각 토큰별 사용 가능한 범위를 보여줍니다. 범위는 토큰 생성시 더 제한될 수 있습니다.

1. 특정 프로젝트로 제한됩니다.
2. 특정 그룹으로 제한됩니다.
3. 러너 등록 및 인증 토큰은 리포지터리에 직접 액세스할 수 없지만, 새로운 러너를 등록 및 인증하는 데 사용될 수 있으며 해당 러너는 리포지터리에 액세스할 수 있는 작업을 실행할 수 있습니다.
4. 특정 엔드포인트에로 제한됩니다.

토큰 접두사

다음 표는 해당하는 경우 각 유형의 토큰에 대한 접두사를 보여줍니다.

GitLab 토큰

외부 시스템 토큰

보안 고려 사항

1. 액세스 토큰을 비밀번호처럼 취급하고 안전하게 보관하세요.
2. 범위가 지정된 토큰을 생성할 때는 실수로 토큰을 유출할 경우의 영향을 줄이기 위해 가능한 한 최소한의 범위를 사용하는 것을 고려하세요.
3. 토큰을 생성할 때, 작업이 완료되면 만료되는 토큰을 설정하는 것을 고려하세요. 예를 들어, 일회성 가져오기를 수행하는 경우 몇 시간 또는 하루 후에 만료되도록 토큰을 설정하면 실수로 유출되어도 쓸모없어집니다.
4. 프로젝트를 쇼케이스하기 위해 데모 환경을 설정하고 해당 프로젝트를 설명하는 비디오를 녹화하거나 블로그 글을 쓰는 경우, 민감한 비밀 (예: 개인 액세스 토큰(PAT), 피드 토큰 또는 트리거 토큰)가 유출되지 않도록 주의하세요. 데모를 마치면 해당 데모 중에 생성된 모든 비밀을 폐기해야 합니다. 자세한 내용은 PAT 폐기를 참조하세요.
5. URL에 액세스 토큰을 추가하는 것은 보안 위험입니다. 특히 클론하거나 원격 리포지터리를 추가할 때, Git은 URL을 평문으로 .git/config 파일에 기록하기 때문입니다. 또한 URL은 일반적으로 프록시 및 응용 프로그램 서버에 의해 기록되므로 시스템 관리자에게 자격 증명이 표시됩니다. 대신 API 호출에 액세스 토큰을 the Private-Token header과 같은 헤더를 사용하여 전달하세요.
6. Git 자격 증명 리포지터리를 사용하여 토큰을 저장할 수도 있습니다.

7. 다음을 하지 마세요:

   • 프로젝트에 평문으로 토큰을 저장하지 마세요.
   • 코드, 콘솔 명령 또는 로그 출력을 이슈, MR 설명 또는 댓글에 붙일 때 토큰을 포함하지 마세요.

   CI에서 외부 비밀 사용과 같은 방법을 고려하세요.

8. 자격 증명을 콘솔 로그 또는 artifact에 기록하지 마세요. 자격 증명 보호 및 마스킹을 고려하세요.
9. 정기적으로 모든 유형의 활성 액세스 토큰을 검토하고 필요하지 않은 것을 폐기하세요. 이에는 다음이 포함됩니다:
   • 개인, 프로젝트 및 그룹 액세스 토큰.
   • 피드 토큰.
   • 트리거 토큰.
   • Runner 등록 토큰.
   • 기타 민감한 비밀 등.