- 개인 액세스 토큰
- OAuth2 토큰
- 표적 토큰
- 프로젝트 액세스 토큰
- 그룹 액세스 토큰
- 배포 토큰
- 배포 키
- 러너 인증 토큰
- Runner registration tokens(사용 중지됨)
- CI/CD 작업 토큰
- GitLab 클러스터 에이전트 토큰
- 기타 토큰
- 사용 가능한 스코프
- 토큰 접두어
- 보안 고려사항
GitLab 토큰 개요
이 문서는 GitLab에서 사용하는 토큰, 그 목적 및 해당하는 경우 보안 지침을 나열합니다.
개인 액세스 토큰
개인 액세스 토큰은 다음과 같이 인증하기 위해 만들 수 있습니다:
- GitLab API.
- GitLab 저장소.
- GitLab 레지스트리.
개인 액세스 토큰의 범위와 만료 날짜를 제한할 수 있습니다. 기본적으로 생성한 사용자의 권한을 상속받습니다.
개인 액세스 토큰 API를 사용하여 개인 액세스 토큰 회전과 같은 프로그래밍 방식으로 조치를 취할 수 있습니다.
개인 액세스 토큰이 만료되기 7일 전에 이메일을 받게 됩니다.
OAuth2 토큰
GitLab은 사용자를 대신하여 다른 서비스가 GitLab API에 액세스할 수 있도록 하기 위해 OAuth2 제공자로 작동할 수 있습니다.
OAuth2 토큰의 범위와 수명을 제한할 수 있습니다.
표적 토큰
표적 토큰은 특별한 유형의 개인 액세스 토큰입니다. 특정 사용자에 대해 관리자만 생성할 수 있습니다. 표적 토큰을 사용하여 GitLab API, 저장소 및 GitLab 레지스트리에 특정 사용자로서 인증하는 응용 프로그램 또는 스크립트를 작성하는 데 도움이 될 수 있습니다.
표적 토큰의 범위를 제한하고 만료 날짜를 설정할 수 있습니다.
프로젝트 액세스 토큰
프로젝트 액세스 토큰은 프로젝트에 대한 범위가 지정됩니다. 개인 액세스 토큰과 마찬가지로 GitLab API, 저장소 및 GitLab 레지스트리에 대해 인증에 사용할 수 있습니다.
프로젝트 액세스 토큰의 범위와 만료 날짜를 제한할 수 있습니다. 프로젝트 액세스 토큰을 생성하면 GitLab은 프로젝트를 위한 프로젝트용 봇 사용자를 생성합니다. 프로젝트용 봇 사용자는 서비스 계정이며 라이선스로서 고려되지 않습니다.
프로젝트 액세스 토큰 API를 사용하여 프로젝트 액세스 토큰 회전과 같은 프로그래밍 방식으로 조치를 취할 수 있습니다.
프로젝트 소유자 및 유지자는 프로젝트 액세스 토큰이 만료되기 7일 전에 이메일을 받습니다.
그룹 액세스 토큰
그룹 액세스 토큰은 그룹에 대한 범위가 지정됩니다. 개인 액세스 토큰과 마찬가지로 GitLab API, 저장소 및 GitLab 레지스트리에 대해 인증에 사용할 수 있습니다.
그룹 액세스 토큰의 범위와 만료 날짜를 제한할 수 있습니다. 그룹 액세스 토큰을 생성하면 GitLab은 그룹용 그룹용 봇 사용자를 생성합니다. 그룹용 봇 사용자는 서비스 계정이며 라이선스로서 고려되지 않습니다.
그룹 액세스 토큰 API를 사용하여 그룹 액세스 토큰 회전과 같은 프로그래밍 방식으로 조치를 취할 수 있습니다.
모든 그룹 소유자는 그룹 액세스 토큰이 만료되기 7일 전에 이메일을 받습니다.
배포 토큰
배포 토큰을 사용하면 프로젝트의 패키지 및 컨테이너 레지스트리 이미지를 다운로드(git clone)하거나 푸시하고 끌어올릴 수 있습니다. 사용자와 비밀번호가 없이 배포 토큰을 사용할 수 없습니다.
프로젝트 유지자 및 소유자가 배포 토큰을 관리할 수 있습니다.
배포 키
배포 키를 사용하여 SSH 공개 키를 GitLab 인스턴스에 가져와서 저장소의 읽기 전용 또는 읽기-쓰기 액세스를 허용할 수 있습니다. 배포 키는 GitLab API나 레지스트리와 함께 사용할 수 없습니다.
예를 들어 CI(Continuous Integration) 서버에 저장소를 복제하는 데 유용합니다. 배포 키를 사용하면 가짜 사용자 계정을 설정할 필요가 없습니다.
프로젝트 유지자 및 소유자는 프로젝트 저장소에 대해 배포 키를 추가하거나 활성화할 수 있습니다.
러너 인증 토큰
GitLab 16.0 이상에서 러너를 등록하기 위해 러너 등록 토큰 대신 러너 인증 토큰을 사용할 수 있습니다. 러너 등록 토큰은 폐기되었습니다.
러너와 해당 구성을 만든 후에 러너 인증 토큰을 받아서 러너를 등록하는 데 사용합니다. 러너 인증 토큰은 러너를 구성하는 데 사용하는 config.toml 파일에 로컬로 저장됩니다.
러너는 작업 대기열에서 작업을 가져올 때 GitLab과 인증하기 위해 러너 인증 토큰을 사용합니다. GitLab과 러너가 인증하면 러너는 작업을 실행하는 데 사용하는 작업 토큰을 수신합니다.
러너 인증 토큰은 러너 기계에 저장됩니다. 다음 실행자의 실행 환경은 작업 토큰만 사용할 수 있으며 러너 인증 토큰을 사용할 수 없습니다:
- Docker Machine
- Kubernetes
- VirtualBox
- Parallels
- SSH
러너 파일 시스템에 대한 악의적인 액세스는 config.toml 파일과 러너 인증 토큰을 노출할 수 있습니다. 공격자는 러너 인증 토큰을 사용하여 러너를 복제할 수 있습니다.
runners API를 사용하여 러너 인증 토큰을 프로그래밍 방식으로 회전하거나 폐기할 수 있습니다.
Runner registration tokens(사용 중지됨)
경고: 러너 등록 토큰을 전달하는 기능이 사용 중지되었으며 일부 구성 인수 지원도 GitLab 18.0에서 제거 예정이며, 이 변경 사항은 대규모 변경 사항입니다. GitLab에서는 새로운 GitLab 러너 토큰 아키텍처를 도입하여 새로운 방법으로 러너를 등록하고 러너 등록 토큰을 제거했습니다.
러너 등록 토큰은 GitLab과 러너를 등록하기 위해 사용됩니다. 그룹 또는 프로젝트 소유자 또는 인스턴스 관리자는 GitLab 사용자 인터페이스를 통해 이를 얻을 수 있습니다. 등록 토큰은 러너 등록에 제한되며 추가적인 범위는 없습니다.
러너 등록 토큰을 사용하여 프로젝트 또는 그룹에서 작업을 실행하는 러너를 추가할 수 있습니다. 러너는 프로젝트 코드에 액세스 할 수 있으므로 프로젝트 및 그룹 수준 권한을 할당할 때 주의하십시오.
CI/CD 작업 토큰
CI/CD 작업 토큰은 작업의 기간 동안에만 유효한 짧은 수명의 토큰입니다. 이 토큰을 사용하여 CI/CD 작업이 제한된 양의 API 엔드포인트에 액세스할 수 있습니다. API 인증은 작업을 트리거하는 사용자의 권한을 사용하여 작업 토큰을 사용합니다.
작업 토큰은 짧은 수명과 제한된 범위로 보호됩니다. 동일한 머신에서 여러 작업이 실행되는 경우(쉘 러너와 유사하게) 토큰이 누출될 수 있습니다. Docker Machine 러너에서는 MaxBuilds=1을 구성하여 러너 머신이 항상 한 번의 빌드만 실행하고 이후에 파괴되도록 하는 것이 좋습니다. 이로 인해 머신 프로비저닝에 시간이 소요되어 성능에 영향을 줄 수 있습니다.
GitLab 클러스터 에이전트 토큰
Kubernetes에 GitLab 에이전트를 등록할 때 GitLab은 클러스터 에이전트가 GitLab과 인증하는 데 사용할 액세스 토큰을 생성합니다.
이 클러스터 에이전트 토큰을 취소하려면 다음 중 하나를 사용할 수 있습니다:
두 방법 모두 토큰, 에이전트 및 프로젝트 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 피드 또는 귀하의 캘린더 피드에 귀하처럼 액세스 할 수 있습니다. 그럴 경우 토큰을 재설정하십시오.
피드 토큰 비활성화
전제 조건:
- 관리자여야 합니다.
- 왼쪽 사이드 바에서 맨 아래에서 관리 영역을 선택합니다.
- 설정 > 일반을 선택합니다.
- 가시성 및 액세스 제어를 확장합니다.
- 피드 토큰 아래에서 피드 토큰 비활성화 확인란을 선택한 다음 변경 사항 저장을 선택합니다.
수신 이메일 토큰
각 사용자에게는 만료되지 않는 수신 이메일 토큰이 있습니다. 이 토큰을 사용하여 사용자는 이메일로 새 이슈를 작성하고 해당 사용자의 개인 프로젝트별 이메일 주소에 포함됩니다. 이 토큰으로는 다른 데이터에 액세스할 수 없습니다. 귀하의 토큰을 가진 사람은 귀하인 것처럼 이슈를 작성하거나 병합 요청을 생성할 수 있습니다. 그럴 경우 토큰을 재설정하십시오.
사용 가능한 스코프
이 테이블은 토큰별 사용 가능한 스코프를 보여줍니다. 스코프는 토큰 생성 시 더 한정적으로 제한될 수 있습니다.
| API 액세스 | 레지스트리 액세스 | 저장소 액세스 | |
|---|---|---|---|
| 개인 액세스 토큰 | ✅ | ✅ | ✅ |
| OAuth2 토큰 | ✅ | 🚫 | ✅ |
| 가장하기 토큰 | ✅ | ✅ | ✅ |
| 프로젝트 액세스 토큰 | ✅(1) | ✅(1) | ✅(1) |
| 그룹 액세스 토큰 | ✅(2) | ✅(2) | ✅(2) |
| 배포 토큰 | 🚫 | ✅ | ✅ |
| 배포 키 | 🚫 | 🚫 | ✅ |
| 러너 등록 토큰 | 🚫 | 🚫 | ✴️(3) |
| 러너 인증 토큰 | 🚫 | 🚫 | ✴️(3) |
| 작업 토큰 | ✴️(4) | 🚫 | ✅ |
- 한 프로젝트에 제한됨.
- 한 그룹에 제한됨.
- 러너 등록 및 인증 토큰은 저장소에 직접 액세스하지는 않지만 저장소에 액세스할 수 있는 작업을 실행할 수 있는 새 러너를 등록하고 인증하는 데 사용될 수 있습니다.
- 특정한 엔드포인트에 제한됨.
토큰 접두어
다음 표는 각 유형의 토큰에 대한 접두어를 보여줍니다(해당하는 경우).
GitLab 토큰
| 토큰 이름 | 접두어 |
|---|---|
| 개인 액세스 토큰 | glpat-
|
| OAuth 응용 프로그램 비밀 | gloas-
|
| 가장하기 토큰 | 해당 없음 |
| 프로젝트 액세스 토큰 | 해당 없음 |
| 그룹 액세스 토큰 | 해당 없음 |
| 배포 토큰 |
gldt- (GitLab 16.7에 추가됨)
|
| 배포 키 | 해당 없음 |
| 러너 등록 토큰 | 해당 없음 |
| 러너 인증 토큰 | glrt-
|
| CI/CD 작업 토큰 |
glcbt- • (GitLab 16.8에 도입됨, prefix_ci_build_tokens이라는 기능 플래그로 비활성화됨.) • (GitLab 16.9에서 GA로 전환됨, prefix_ci_build_tokens 플래그 제거됨.)
|
| 트리거 토큰 | glptt-
|
| 레거시 러너 등록 토큰 | GR1348941 |
| 피드 토큰 | glft-
|
| 수신 메일 토큰 | glimt-
|
| Kubernetes용 GitLab 에이전트 토큰 | glagent-
|
| GitLab 세션 쿠키 | _gitlab_session=
|
| SCIM 토큰 |
glsoat- • (GitLab 16.8에 도입됨, prefix_scim_tokens이라는 기능 플래그로 비활성화됨.) • (GitLab 16.9에서 GA로 전환됨, prefix_scim_tokens 플래그 제거됨.)
|
| 특징 플래그 클라이언트 토큰 | glffct-
|
외부 시스템 토큰
| 토큰 이름 | 접두어 |
|---|---|
| 오마모리 토큰 | omamori_pat_
|
| AWS 자격 증명 | AKIA
|
| GCP 자격 증명 | 해당 없음 |
보안 고려사항
- 액세스 토큰을 비밀번호처럼 취급하여 안전하게 보관하세요.
- 스코프가 지정된 토큰을 생성할 때는 실수로 토큰이 노출될 경우에 대비하여 가능한 가장 제한된 스코프를 사용하는 것을 고려하세요.
- 토큰을 생성할 때 해당 작업이 완료된 후에 만료되도록 토큰을 설정하는 것을 고려하세요. 예를 들어, 일회성 가져오기를 수행하는 경우 토큰을 수시간 또는 하루 후에 만료되도록 설정하세요. 이렇게 하면 만료되면 쓸모 없어져서 노출되어도 영향을 줄일 수 있습니다.
- 프로젝트를 소개하는 데 사용할 데모 환경을 설정하고 해당 프로젝트를 설명하는 동영상을 녹화하거나 블로그 글을 작성하는 경우, 민감한 시크릿(예: 개인 액세스 토큰(PAT), 피드 토큰 또는 트리거 토큰)이 노출되지 않았는지 확인하세요. 데모를 완료했다면 해당 데모 중에 생성된 모든 시크릿을 폐기해야 합니다. 자세한 내용은 PAT 취소를 참조하세요.
- URL에 액세스 토큰을 추가하는 것은 보안 위험입니다, 특히 복제하거나 원격 추가할 때에 Git은 URL을 평문으로
.git/config파일에 기록하기 때문입니다. 또한 URL은 보통 프록시 및 응용 프로그램 서버에 의해 로깅되므로 시스템 관리자에게 자격 증명이 표시됩니다. 대신에 Private-Token 헤더와 같은 헤더를 사용하여 API 호출에 액세스 토큰을 전달하세요. - Git 자격 증명 저장소를 사용하여 토큰을 저장할 수도 있습니다.
-
다음을 하지 마십시오:
- 프로젝트에서 액세스 토큰을 평문으로 저장하지 마십시오.
- 코드, 콘솔 명령 또는 로그 출력을 이슈, MR 설명 또는 코멘트에 붙일 때 액세스 토큰을 포함하지 마십시오.
CI에서 외부 시크릿 사용 고려 등을 고려하세요.
- 콘솔 로그나 아티팩트에 자격 증명을 로깅하지 마세요. CI/CD 변수를 보호하고 마스킹하는 것을 고려하세요.
-
모든 유형의 활성 액세스 토큰을 정기적으로 검토하고 더 이상 필요하지 않은 토큰을 폐기하세요. 이에는 다음이 포함됩니다:
- 개인, 프로젝트 및 그룹 액세스 토큰.
- 피드 토큰.
- 트리거 토큰.
- 러너 등록 토큰.
- 기타 민감한 시크릿 등.
도움말