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

보안 고려 사항#

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

• 토큰을 비밀번호처럼 취급하고 안전하게 보관하세요.
• 범위가 지정된 토큰을 만들 때 실수로 누출된 토큰의 영향을 줄이기 위해 가능한 가장 제한적인 범위를 사용하세요.
  • 별도의 프로세스가 다른 범위를 필요로 하는 경우(예: read 및 write), 각 범위에 대해 별도의 토큰을 사용하는 것을 고려하세요. 하나의 토큰이 유출되면 전체 API 액세스와 같은 넓은 범위를 가진 단일 토큰보다 적은 액세스를 제공합니다.
• 토큰을 만들 때:
  • 아래의 토큰 명명 지침에 따라 이름을 선택하세요.
  • 작업이 완료되면 만료되는 토큰을 설정하는 것을 고려하세요. 예를 들어 일회성 가져오기를 수행해야 하는 경우 토큰이 몇 시간 후에 만료되도록 설정하세요.
  • 관련 URL을 포함한 추가 컨텍스트를 제공하는 설명을 추가하세요.
• URL 대신 헤더를 통해 토큰을 전달하세요:
  • 개인, 프로젝트 및 그룹 액세스 토큰에는 PRIVATE-TOKEN을 사용하세요.
  • 작업 토큰에는 JOB-TOKEN을 사용하세요.
• 데모 환경이 있는 경우 프로젝트에 대한 비디오를 녹화하거나 블로그 게시물을 게시한 후 모든 토큰을 취소하세요.
• Git 자격 증명 저장소를 사용하여 토큰을 저장할 수 있습니다.
• 모든 유형의 모든 활성 액세스 토큰을 정기적으로 검토하고 필요하지 않은 토큰은 취소하세요.

금지 사항:

• URL에 토큰을 추가하지 마세요:
  • URL에 토큰이 있는 상태로 원격을 클론하거나 추가하면 Git은 URL을 .git/config 파일에 일반 텍스트로 기록합니다.
  • URL은 종종 프록시 및 애플리케이션 서버에 기록되어 시스템 관리자에게 해당 자격 증명이 노출될 수 있습니다.
• 프로젝트에 일반 텍스트로 토큰을 저장하지 마세요.
  • 토큰이 GitLab CI/CD의 외부 시크릿인 경우 CI/CD에서 외부 시크릿 사용 방법을 검토하세요.
• 코드, 콘솔 명령 또는 로그 출력을 이슈, MR 설명, 댓글 또는 다른 자유 텍스트 입력에 붙여넣을 때 토큰을 포함하지 마세요.
• 콘솔 로그 또는 아티팩트에 자격 증명을 기록하지 마세요. 자격 증명을 보호하고 마스킹하는 것을 고려하세요.

토큰 명명 지침#

액세스 토큰에 대한 명확하고 일관된 명명 규칙은 다음에 도움이 됩니다:

• 활성 토큰을 감사할 때 토큰의 목적과 소유자를 빠르게 식별합니다.

• 토큰을 교체하거나 취소하기 전에 여전히 필요한지 여부를 결정합니다.

• 다른 프로세스가 의존하는 토큰을 실수로 취소하는 위험을 줄입니다.

권장 명명 형식#

누가 토큰을 만들었는지, 무엇에 사용되는지, 어디서 사용되는지 세 가지 질문에 답하는 이름을 사용하세요.

실용적인 형식은 다음과 같습니다:

<purpose>-<context>-<environment>

예를 들어:

명명 지침#

• 구체적으로 작성하세요. test, mytoken, token1, GITLAB_API_TOKEN, API_TOKEN 또는 default와 같은 일반적인 이름을 피하세요. 이런 이름은 감사 중에 토큰의 목적을 파악하는 것을 불가능하게 합니다.

• 사용하는 시스템 또는 도구를 포함하세요. 토큰이 특정 애플리케이션, 스크립트 또는 통합에 사용되는 경우 해당 이름을 포함하세요. 예: terraform-state-backend 또는 grafana-metrics-reader.

• 환경을 포함하세요. 해당되는 경우 토큰이 production, staging 또는 development를 대상으로 하는지 명시하세요. 이는 프로덕션 토큰이 낮은 환경에서 실수로 사용되는 것을 방지합니다.

• 민감한 정보를 포함하지 마세요. 토큰 이름은 감사 로그 및 UI에서 볼 수 있으므로 사용자 이름, 이메일 주소 또는 기타 개인 식별 정보(PII)를 포함하지 마세요.

• 소문자와 하이픈을 사용하세요. 일관된 대소문자와 구분 기호는 이름을 읽고 검색하기 쉽게 만듭니다. 예를 들어 CI_Deploy_Production 대신 ci-deploy-production을 사용하세요.

• 추가 컨텍스트에는 설명 필드를 사용하세요. 토큰 설명 필드(GitLab 17.7 이상에서 사용 가능)는 이름에 맞지 않는 세부 정보(예: 토큰을 요청한 이슈 링크나 소유 팀)를 추가하기에 좋은 곳입니다.

자동화에 사용되는 토큰#

CI/CD 파이프라인, 스크립트 또는 기타 자동화 프로세스에 사용되는 토큰의 경우:

• 시스템 또는 파이프라인 이름을 접두사로 사용하세요. 예: ci-, terraform- 또는 k8s-.

• 토큰이 운영하는 프로젝트 또는 그룹을 포함하세요. 예: ci-deploy-my-project-production.

• 자동화를 위해 개인 액세스 토큰 대신 프로젝트 액세스 토큰 또는 그룹 액세스 토큰 사용을 고려하세요. 이는 개별 사용자 계정에 연결되지 않습니다.

개인 개발에 사용되는 토큰#

로컬 개발 또는 개인 도구에 사용되는 토큰의 경우:

• 감사 중에 토큰을 당신에게 추적할 수 있도록 사용자 이름 또는 식별자를 포함하세요. 예: local-dev-jsmith 또는 vscode-gitlab-jsmith.

• 단일 광범위한 범위의 토큰을 재사용하는 대신 별도의 도구나 목적을 위해 별도의 토큰을 만드세요.

CI/CD의 토큰#

광범위한 범위로 인해 가능한 곳에서 개인 액세스 토큰을 CI/CD 변수로 사용하는 것을 피하세요. CI/CD 작업에서 다른 리소스에 대한 액세스가 필요한 경우 액세스 범위가 가장 적은 것부터 많은 순서로 다음 중 하나를 사용하세요:

1. 작업 토큰 (가장 낮은 액세스 범위)
2. 프로젝트 토큰
3. 그룹 토큰

CI/CD 변수 보안에 대한 추가 권고 사항:

• 모든 자격 증명에 시크릿 저장소를 사용하세요.
• 민감한 정보를 포함하는 CI/CD 변수는 보호되고, 마스킹되고, 숨겨져야 합니다.

개인 액세스 토큰#

다음으로 인증하기 위해 개인 액세스 토큰을 만들 수 있습니다:

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

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

개인 액세스 토큰 API를 사용하여 개인 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

개인 액세스 토큰이 곧 만료되면 이메일을 받습니다.

권한을 위한 토큰이 필요한 CI/CD 작업을 고려할 때 특히 CI/CD 변수로 저장된 경우 개인 액세스 토큰을 사용하는 것을 피하세요. CI/CD 작업 토큰과 프로젝트 액세스 토큰은 훨씬 적은 위험으로 동일한 결과를 달성할 수 있습니다.

OAuth 2.0 토큰#

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

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

가장 토큰#

가장 토큰은 특별한 유형의 개인 액세스 토큰입니다. 특정 사용자를 위해 관리자만 만들 수 있습니다. 가장 토큰은 특정 사용자로 GitLab API, 리포지토리 및 GitLab 레지스트리에 인증하는 애플리케이션 또는 스크립트를 구축하는 데 도움이 될 수 있습니다.

가장 토큰에 대한 범위를 제한하고 만료 날짜를 설정할 수 있습니다.

프로젝트 액세스 토큰#

프로젝트 액세스 토큰은 프로젝트에 범위가 지정됩니다. 개인 액세스 토큰과 마찬가지로 다음으로 인증하는 데 사용할 수 있습니다:

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

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

프로젝트 액세스 토큰 API를 사용하여 프로젝트 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

메인테이너 또는 오너 역할을 가진 프로젝트의 구성원은 프로젝트 액세스 토큰이 거의 만료될 때 이메일을 받습니다.

그룹 액세스 토큰#

그룹 액세스 토큰은 그룹에 범위가 지정됩니다. 개인 액세스 토큰과 마찬가지로 다음으로 인증하는 데 사용할 수 있습니다:

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

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

그룹 액세스 토큰 API를 사용하여 그룹 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

오너 역할을 가진 그룹의 구성원은 그룹 액세스 토큰이 거의 만료될 때 이메일을 받습니다.

배포 토큰#

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

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

배포 키#

배포 키는 SSH 공개 키를 GitLab 인스턴스로 가져와 리포지토리에 대한 읽기 전용 또는 읽기-쓰기 액세스를 허용합니다. 배포 키는 GitLab API 또는 레지스트리와 함께 사용할 수 없습니다.

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

프로젝트에 배포 키를 추가하거나 활성화하려면 최소 메인테이너 역할이 있어야 합니다.

러너 인증 토큰#

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

러너를 만들고 구성한 후 러너를 등록하는 데 사용하는 러너 인증 토큰을 받습니다. 러너 인증 토큰은 러너를 구성하는 데 사용하는 config.toml 파일에 로컬로 저장됩니다.

러너는 러너 인증 토큰을 사용하여 작업 큐에서 작업을 선택할 때 GitLab에 인증합니다. 러너가 GitLab에 인증하면 러너는 작업을 실행하는 데 사용하는 작업 토큰을 받습니다.

러너 인증 토큰은 러너 머신에 남아 있습니다. 다음 실행기의 실행 환경은 러너 인증 토큰이 아닌 작업 토큰에만 액세스할 수 있습니다:

• Docker Machine
• Kubernetes
• VirtualBox
• Parallels
• SSH

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

러너 API를 사용하여 러너 인증 토큰을 교체하거나 취소할 수 있습니다.

러너 등록 토큰 (레거시)#

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

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

CI/CD 작업 토큰#

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

작업 토큰은 짧은 수명과 제한된 범위로 보안이 강화됩니다. 여러 작업이 동일한 머신에서 실행되는 경우(예: 쉘 러너를 사용하는 경우) 이 토큰이 유출될 수 있습니다. 프로젝트 허용 목록을 사용하여 작업 토큰이 액세스할 수 있는 것을 추가로 제한할 수 있습니다.

Docker Machine 러너에서 러너 머신이 하나의 빌드만 실행하고 이후 삭제되도록 하기 위해 MaxBuilds=1을 구성해야 합니다. 프로비저닝에 시간이 걸리므로 이 구성은 성능에 영향을 줄 수 있습니다.

GitLab 클러스터 에이전트 토큰#

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

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

• 에이전트 API로 토큰을 취소하세요.
• 토큰을 재설정하세요.

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

# Find token ID
Clusters::AgentToken.find_by_token('glagent-xxx').id

# Find agent ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
=> 1234

# Find project ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
=> 12345

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

# Revoke token with RevokeService, including generating an audit event
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# Revoke token manually, which does not generate an audit event
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

기타 토큰#

피드 토큰#

각 사용자는 만료되지 않는 장기 피드 토큰을 가지고 있습니다. 이 토큰을 사용하여 다음을 인증하세요:

• RSS 리더, 개인화된 RSS 피드를 로드하기 위해
• 캘린더 애플리케이션, 개인화된 캘린더를 로드하기 위해

이 토큰을 사용하여 다른 데이터에 액세스할 수 없습니다.

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

토큰을 가진 사람은 기밀 이슈를 포함하여 당신인 것처럼 피드 활동을 볼 수 있습니다. 토큰이 유출되었다고 생각되면 즉시 토큰을 재설정하세요.

피드 토큰 비활성화#

사전 요구 사항:

• 관리자여야 합니다.

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. 설정 > 일반을 선택하세요.
3. 가시성 및 액세스 제어를 확장하세요.
4. 피드 토큰 아래에서 피드 토큰 비활성화 체크박스를 선택한 다음 변경 사항 저장을 선택하세요.

수신 이메일 토큰#

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

이 토큰을 사용하여 다른 데이터에 액세스할 수 없습니다. 토큰을 가진 사람은 당신인 것처럼 이슈와 병합 요청을 만들 수 있습니다. 토큰이 유출되었다고 생각되면 즉시 토큰을 재설정하세요.

작업 공간 토큰#

히스토리

• GitLab 18.2에서 도입되었습니다.

각 작업 공간에는 만료되지 않는 내부적으로 자동으로 관리되는 토큰이 있습니다. 작업 공간과의 HTTP 및 SSH 통신을 허용합니다. 작업 공간이 실행 중 상태에 있도록 요청될 때마다 존재하며 자동으로 삽입되고 작업 공간에서 사용됩니다.

중지된 작업 공간을 시작하면 새 작업 공간 토큰이 만들어집니다. 실행 중인 작업 공간을 재시작하면 기존 토큰이 삭제되고 새 토큰이 만들어집니다.

이 내부 토큰을 직접 보거나 관리할 수 없습니다. 이 토큰을 사용하여 다른 데이터에 액세스할 수 없습니다.

작업 공간 토큰을 취소하려면 작업 공간을 중지 또는 종료하세요. 토큰이 즉시 삭제됩니다.

사용 가능한 범위#

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

각주:

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

토큰 접두사#

다음 표는 각 유형의 토큰에 대한 접두사를 보여줍니다. 개인 액세스 토큰을 제외하고, 이러한 접두사는 표준 식별로 설계되었으므로 구성할 수 없습니다.