• 개인 액세스 토큰
• OAuth 2.0 토큰
• 표현 토큰(lang:ko)
• 프로젝트 액세스 토큰
• 그룹 액세스 토큰
• 배포 토큰
• 배포 키
• 러너 인증 토큰
• 러너 등록 토큰(무시되었습니다)
• CI/CD 작업 토큰
• GitLab 클러스터 에이전트 토큰
• 기타 토큰
  • 피드 토큰
    • 피드 토큰 비활성화
  • 수신 이메일 토큰
• 사용 가능한 범위
• 토큰 접두사
• 보안 고려 사항

GitLab 토큰 개요

이 문서는 GitLab에서 사용되는 토큰, 그 목적 및 적용되는 경우 보안 가이던스를 나열합니다.

개인 액세스 토큰

개인 액세스 토큰을 생성하여 다음과 같이 인증할 수 있습니다:

• GitLab API.
• GitLab 저장소.
• GitLab 레지스트리.

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

개인 액세스 토큰 API를 사용하여 개인 액세스 토큰을 회전하는 등 프로그래밍적으로 조치를 취할 수 있습니다.

토큰의 만료까지 7일 이하로 남아있을 때 이메일을 수신합니다.

OAuth 2.0 토큰

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

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

표현 토큰(lang:ko)

표현 토큰은 특정 사용자를 위해 관리자만이 생성할 수 있는 특별한 유형의 개인 액세스 토큰입니다. 표현 토큰을 사용하면 GitLab API, 저장소 및 레지스트리에 특정 사용자로 인증하는 애플리케이션 또는 스크립트를 작성할 수 있습니다.

표현 토큰의 범위를 제한하고 만료 날짜를 설정할 수 있습니다.

프로젝트 액세스 토큰

프로젝트 액세스 토큰은 프로젝트에 범위가 지정된 토큰입니다. 개인 액세스 토큰과 마찬가지로 GitLab API, GitLab 저장소, GitLab 레지스트리에 인증하는 데 사용할 수 있습니다.

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

프로젝트 액세스 토큰 API를 사용하여 프로젝트 액세스 토큰을 회전하는 등 프로그래밍적으로 조치를 취할 수 있습니다.

최소한 Maintainer 역할을 가진 프로젝트의 직접 멤버는 프로젝트 액세스 토큰의 만료까지 7일 이하로 남아있을 때 이메일을 수신합니다. 상속된 멤버는 이메일을 수신하지 않습니다.

그룹 액세스 토큰

그룹 액세스 토큰은 그룹에 범위가 지정된 토큰입니다. 개인 액세스 토큰과 마찬가지로 GitLab API, GitLab 저장소, GitLab 레지스트리에 인증하는 데 사용할 수 있습니다.

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

그룹 액세스 토큰 API를 사용하여 그룹 액세스 토큰을 회전하는 등 프로그래밍적으로 조치를 취할 수 있습니다.

그룹의 직접 멤버 중 소유자 역할을 가진 멤버는 그룹 액세스 토큰의 만료까지 7일 이하로 남아있을 때 이메일을 수신합니다. 상속된 멤버는 이메일을 수신하지 않습니다.

배포 토큰

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

배포 토큰을 관리하려면 최소한 Maintainer 역할을 가진 프로젝트의 멤버여야 합니다.

배포 키

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

배포 키를 사용하여 CI 서버에서 레포지토리를 복제할 때 가짜 사용자 계정을 설정할 필요가 없습니다.

프로젝트에 배포 키를 추가하거나 활성화하려면 최소한 Maintainer 역할을 가진 필요가 있습니다.

러너 인증 토큰

GitLab 16.0 이상에서 러너를 등록하려면 러너 등록 토큰 대신 러너 인증 토큰을 사용할 수 있습니다. 러너 등록 토큰은 무시되었습니다.

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

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

러너 인증 토큰은 러너 기계에 남아 있습니다. 다음 실행기의 실행 환경은 작업 토큰만 사용하며 러너 인증 토큰을 사용하지 않습니다.

• Docker Machine
• Kubernetes
• VirtualBox
• Parallels
• SSH

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

러너 API를 사용하여 러너 인증 토큰을 회전 또는 폐기할 수 있습니다.

러너 등록 토큰(무시되었습니다)

경고: 러너 등록 토큰을 전달하는 기능은 무시되었으며 특정 구성 인수에 대한 지원도 GitLab 18.0에서 제거할 예정입니다. 이 변경 사항은 호환성이 없는 변경입니다. GitLab은 새로운 GitLab 러너 토큰 아키텍처를 구현하여 새로운 러너를 등록하고 러너 등록 토큰을 제거할 수 있는 새로운 방법을 도입했습니다.

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

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

CI/CD 작업 토큰

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

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

GitLab 클러스터 에이전트 토큰

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

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

• 에이전트 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은 다른 토큰으로 생성되며 단일 피드에 대해서만 유효합니다.

토큰을 유출된 것으로 판단되면 토큰을 재설정하십시오.

피드 토큰 비활성화

전제 조건:

• 관리자여야 합니다.

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

수신 이메일 토큰

각 사용자에게 만료되지 않는 수신 이메일 토큰이 있습니다. 이 토큰은 개인 프로젝트와 연결된 이메일 주소에 포함됩니다. 이 토큰을 사용하여 이메일로 새 이슈 작성을 할 수 있습니다.

이 토큰으로 다른 데이터에 액세스할 수는 없습니다. 해당 토큰을 가진 사용자는 자신이라고 할 수 있는 것처럼 이슈를 생성하고 병합 요청을 만들 수 있습니다. 토큰이 유출된 것으로 생각된다면 즉시 토큰을 재설정하십시오.

사용 가능한 범위

이 표는 토큰별 기본 범위를 보여줍니다. 일부 토큰의 경우 토큰을 생성할 때 범위를 더 제한할 수 있습니다.

각주:

1. 특정 프로젝트로 제한됨.
2. 특정 그룹으로 제한됨.
3. 러너 등록 및 인증 토큰은 저장소에 직접 액세스하지 않지만 저장소에 액세스할 수 있는 새 러너를 등록하고 인증하는 데 사용될 수 있습니다.
4. 특정 일부 엔드포인트만 가능함.

토큰 접두사

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

보안 고려 사항

귀하의 토큰을 안전하게 유지하기 위해:

• 액세스 토큰을 암호처럼 취급하고 안전하게 보관합니다.
• 스코프가 지정된 토큰을 생성할 때, 실수로 토큰을 누설할 가능성을 줄이기 위해 가능한 한 제한된 스코프를 사용합니다.
• 토큰을 생성할 때, 작업이 완료된 후에 토큰이 만료되도록 설정하는 것을 고려합니다. 예를 들어, 일회성 가져오기를 수행해야 하는 경우 토큰을 수시간 후에 만료되도록 설정합니다.
• 프로젝트를 쇼케이스하고 있는 데모 환경을 설정하고 해당 프로젝트를 설명하는 비디오를 녹화하거나 블로그 글을 작성할 경우, 실수로 비밀을 누설하지 않도록 주의합니다. 데모가 완료된 후에 데모 중에 생성된 모든 비밀을 폐기합니다.
• 액세스 토큰을 URL에 추가하는 것은 보안 위험입니다. 특히 URL을 작성하거나 원격지를 추가할 때, Git은 URL을 평문으로 .git/config 파일에 작성합니다. URL은 또한 프록시 및 응용 프로그램 서버에 의해 자주 기록되며, 이는 시스템 관리자에게 해당 자격 증명을 누설시킵니다. 대신, Private-Token과 같은 헤더로 액세스 토큰을 API 호출에 전달합니다.
• Git 자격 증명 저장소를 사용하여 토큰을 저장할 수 있습니다.
• 정기적으로 모든 유형의 활성 액세스 토큰을 검토하고 필요 없는 것들을 폐기합니다.

하지 마십시오:

• 프로젝트에서 평문으로 토큰을 저장하지 마십시오. 토큰이 GitLab CI/CD의 외부 비밀인 경우, CI에서 외부 비밀 사용을 검토하세요.
• 이슈, MR 설명 또는 코멘트에 코드, 콘솔 명령 또는 로그 출력을 붙일 때 토큰을 포함하지 마십시오.
• 콘솔 로그나 아티팩트에 자격 증명을 기록하지 마십시오. 자격 증명을 보호 및 마스킹하는 것을 고려하세요.