개인 엑세스 토큰

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 12.6에서 도입된 만료 예정 알림
  • GitLab 12.6에서 도입된 토큰 수명 제한
  • GitLab 13.3에서 도입된 만료 예정 알림 추가
  • GitLab 14.1에서 도입된 토큰 이름 및 스코프 미리 채우기

개인 엑세스 토큰은 OAuth2의 대체품으로 사용되며 다음과 같이 사용될 수 있습니다:

  • GitLab API로 인증
  • HTTP 기본 인증을 사용하여 Git과 인증

두 경우 모두 비밀번호 대신 개인 엑세스 토큰으로 인증합니다.

경고: 만료되지 않은 개인 엑세스 토큰을 생성하는 기능이 GitLab 15.4에서 폐기되었으며, GitLab 16.0에서 제거되었습니다. GitLab 16.0 이후, 만료 날짜가 없는 기존 개인 엑세스 토큰은 자동으로 현재 날짜로부터 365일 뒤의 만료 날짜가 지정됩니다. 만료 날짜의 자동 추가는 GitLab.com에서 16.0 지점에서 발생합니다. 자체 호스팅된 인스턴스가 GitLab 16.0으로 업그레이드되면 자동으로 만료 날짜가 추가됩니다. 이 변경 사항은 파괴적인 변경입니다.

개인 엑세스 토큰은 다음과 같습니다:

참고: 필요하지만 인증하는 경우 GitLab 사용자명은 무시됩니다. GitLab에서 사용자명 사용을 추적하기 위한 이슈가 있습니다.

API를 사용하여 개인 엑세스 토큰을 사용하여 인증하는 방법에 대한 예제는 API 문서를 참조하세요.

대신, GitLab 관리자는 API를 사용하여 가장하기 토큰을 생성할 수 있습니다. 가장하기 토큰을 사용하여 특정 사용자로써의 인증을 자동화할 수 있습니다.

개인 엑세스 토큰 생성

원하는 만큼 많은 개인 엑세스 토큰을 생성할 수 있습니다.

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 수정을 선택합니다.
  3. 왼쪽 사이드바에서 액세스 토큰을 선택합니다.
  4. 새 토큰 추가를 선택합니다.
  5. 토큰의 이름과 만료 날짜를 입력합니다.
    • 토큰은 해당 날짜에 UTC 자정에 만료됩니다.
    • 만료 날짜를 입력하지 않으면 자동으로 현재 날짜로부터 365일 뒤의 만료 날짜로 설정됩니다.
    • 기본적으로 이 날짜는 현재 날짜로부터 최대 365일 후의 날짜일 수 있습니다.
  6. 원하는 스코프를 선택합니다.
  7. 개인 엑세스 토큰 생성을 선택합니다.

개인 엑세스 토큰을 안전한 위치에 저장하세요. 페이지를 나가면 토큰에 더 이상 액세스할 수 없습니다.

개인 엑세스 토큰 이름과 스콥 미리 채우기

개인 엑세스 토큰 페이지로 직접 링크하고 이름과 스코프 목록으로 폼을 미리 채울 수 있습니다. 이를 위해 URL에 name 매개변수와 쉼표로 구분된 스코프 목록을 추가할 수 있습니다. 예를 들어: 

https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry

경고: 개인 엑세스 토큰은 신중하게 처리해야 합니다. 개인 엑세스 토큰의 관리에 대한 지침은 토큰 보안 고려 사항을 참조하세요 (예: 짧은 만료 기간 설정 및 최소한의 스코프 사용).

개인 액세스 토큰 취소

언제든지 개인 액세스 토큰을 취소할 수 있습니다.

  1. 좌측 사이드 바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 좌측 사이드 바에서 액세스 토큰을 선택합니다.
  4. 활성 개인 액세스 토큰 영역에서 관련된 토큰에 대해 취소를 선택합니다.
  5. 확인 대화상자에서 취소를 선택합니다.

개인 액세스 토큰 비활성화

Tier: 프리미엄, 얼티메이트 Offering: Self-managed, GitLab Dedicated

필수 조건:

  • 관리자여야 합니다.

GitLab 15.7 이상에서 애플리케이션 설정 API를 사용하여 개인 액세스 토큰을 비활성화할 수 있습니다.

토큰 마지막 사용 시간 확인

  • GitLab 13.2에서 도입되었습니다. 토큰 사용 정보는 24시간마다 업데이트됩니다.
  • 토큰 사용 정보 갱신 주기는 GitLab 16.1에서 24시간에서 10분으로 변경되었습니다.

토큰 사용 정보는 10분마다 업데이트됩니다. GitLab은 토큰을 사용하여 다음 작업을 수행할 때 토큰이 사용된 것으로 간주합니다.

  • REST 또는 GraphQL API로 인증하기
  • Git 작업 수행

토큰이 마지막으로 사용된 시간을 확인하려면:

  1. 좌측 사이드 바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 좌측 사이드 바에서 액세스 토큰을 선택합니다.
  4. 활성 개인 액세스 토큰 영역에서 관련 토큰의 마지막 사용 날짜를 확인합니다.

개인 액세스 토큰 스코프

  • GitLab 16.0에서 더 이상 개인 액세스 토큰이 컨테이너 또는 패키지 레지스트리에 액세스할 수 없음이 도입되었습니다.
  • k8s_proxy는 GitLab 16.4에 플래그k8s_proxy_pat로 함께 도입되었습니다. 기본적으로 활성화됩니다.
  • 기능 플래그 k8s_proxy_pat는 GitLab 16.5에서 제거되었습니다.

개인 액세스 토큰은 할당된 스코프를 기반으로 작업을 수행할 수 있습니다.

스코프 액세스
api 컨테이너 레지스트리, 의존성 프록시, 패키지 레지스트리를 포함한 모든 그룹 및 프로젝트, API에 대한 완전한 읽기/쓰기 액세스를 부여합니다. 또한 HTTP를 통해 Git을 사용하여 저장소 및 레지스트리에 대한 완전한 읽기/쓰기 액세스를 부여합니다.
read_user /user API 엔드포인트를 통해 인증된 사용자의 프로필에 대한 읽기 전용 액세스를 부여합니다. 이에는 사용자 이름, 공개 이메일 및 전체 이름이 포함됩니다. 또한 /users 하위의 읽기 전용 API 엔드포인트에 대한 액세스도 부여합니다.
read_api 모든 그룹 및 프로젝트, 컨테이너 레지스트리, 패키지 레지스트리에 대한 읽기 액세스를 부여합니다. (GitLab 12.10에서 도입)
read_repository Git-over-HTTP 또는 Repository Files API를 사용하여 비공개 프로젝트의 저장소에 대한 읽기 전용 액세스를 부여합니다.
write_repository API를 사용하지 않고 Git-over-HTTP를 사용하여 비공개 프로젝트의 저장소에 대한 읽기/쓰기 액세스를 부여합니다.
read_registry 프로젝트가 비공개이며 인가가 필요한 경우 컨테이너 레지스트리 이미지에 대한 읽기 전용(풀) 액세스를 부여합니다. 컨테이너 레지스트리가 활성화된 경우에만 사용할 수 있습니다.
write_registry 프로젝트가 비공개이며 인가가 필요한 경우 컨테이너 레지스트리 이미지에 대한 읽기/쓰기 (푸시) 액세스를 부여합니다. (GitLab 12.10에서 도입)
sudo 관리자로 인증되었을 때 시스템 내의 모든 사용자로 API 작업을 수행할 수 있는 권한을 부여합니다.
admin_mode Admin Mode가 활성화된 경우 관리자로서 API 작업을 수행할 수 있는 권한을 부여합니다. (GitLab 15.8에서 도입)
create_runner 실행자를 생성할 수 있는 권한을 부여합니다.
ai_features GitLab Duo를 위한 API 작업을 수행할 수 있는 권한을 부여합니다. 이 스코프는 JetBrains용 GitLab Duo 플러그인과 함께 작동하도록 설계되었습니다. 다른 모든 확장 기능의 경우 스코프 요구 사항을 참조하세요.
k8s_proxy Kubernetes 에이전트를 사용하여 Kubernetes API 호출을 수행할 수 있는 권한을 부여합니다.
read_service_ping 관리자로 인증되었을 때 API를 통해 서비스 핑 페이로드를 다운로드할 수 있는 권한을 부여합니다. (GitLab 16.8에서 도입)

경고: 외부 인가를 활성화한 경우 개인 액세스 토큰으로 컨테이너나 패키지 레지스트리에 액세스할 수 없습니다. 이러한 레지스트리에 개인 액세스 토큰을 사용하는 경우 이 조치는 해당 토큰의 사용을 방해합니다. 컨테이너나 패키지 레지스트리에 개인 액세스 토큰을 사용하려면 외부 인가를 비활성화하세요.

개인 액세스 토큰 만료 시기

개인 액세스 토큰은 사용자가 정의한 날짜에 따라 UTC 기준으로 자정인 00:00 AM에 만료됩니다.

  • GitLab은 매일 01시 00분 UTC에 7일 내에 만료되는 개인 액세스 토큰을 식별하기 위해 확인 작업을 실행합니다. 이러한 토큰의 소유자들에게 이메일로 알림이 전송됩니다.
  • GitLab은 매일 02시 00분 UTC에 현재 날짜에 만료되는 개인 액세스 토큰을 식별하기 위해 확인 작업을 실행합니다. 이러한 토큰의 소유자들에게 이메일로 알림이 전송됩니다.
  • GitLab Ultimate에서는 관리자가 액세스 토큰의 허용 가능한 수명을 제한할 수 있습니다. 설정하지 않으면 개인 액세스 토큰의 최대 허용 수명은 365일입니다.
  • GitLab Free 및 Premium에서는 개인 액세스 토큰의 최대 허용 수명이 365일입니다.
  • 개인 액세스 토큰을 생성할 때 만료 날짜를 설정하지 않으면 만료 날짜가 토큰의 최대 허용 수명까지로 설정됩니다. 최대 허용 수명이 설정되지 않은 경우, 기본 만료 날짜는 생성 날짜로부터 365일 후로 설정됩니다.

만료 날짜가 없는 서비스 계정 개인 액세스 토큰 생성

만료 날짜가 없는 서비스 계정용 개인 액세스 토큰을 생성할 수 있습니다. 이러한 개인 액세스 토큰은 서비스 계정용이 아닌 개인 액세스 토큰과는 달리 만료되지 않습니다.

참고: 서비스 계정용 개인 액세스 토큰을 만료 날짜 없이 생성할 수 있게 허용하는 것은 설정 변경 이후에 생성된 토큰에만 영향을 미치며, 기존 토큰에는 영향을 미치지 않습니다.

GitLab.com

필수 조건:

  • 최상위 그룹에서 소유자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. Settings > General > Permissions and group features를 선택합니다.
  3. Service account token expiration 확인란을 해제합니다.

이제 서비스 계정 사용자를 위해 만료 날짜가 없는 개인 액세스 토큰을 생성할 수 있습니다.

Self-managed GitLab

필수 조건:

  • 자체 관리형 인스턴스의 관리자이어야 합니다.
  1. 왼쪽 사이드바에서 가장 아래에 있는 Admin Area를 선택합니다.
  2. Settings > General을 선택합니다.
  3. Account and limit을 확장합니다.
  4. Service account token expiration 확인란을 해제합니다.

이제 서비스 계정 사용자를 위해 만료 날짜가 없는 개인 액세스 토큰을 생성할 수 있습니다.

프로그래밍 방식으로 개인 액세스 토큰 생성

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

테스트나 자동화의 일환으로 미리 정의된 개인 액세스 토큰을 생성할 수 있습니다.

필수 조건:

프로그래밍 방식으로 개인 액세스 토큰을 생성하려면:

  1. Rails 콘솔을 엽니다: 

    sudo gitlab-rails console

  2. 다음 명령을 실행하여 사용자 이름, 토큰 및 스코프를 참조합니다.

    토큰은 20자여야 합니다. 스코프는 유효해야 하며 소스 코드에서 확인할 수 있습니다.

    예를 들어, 1년 후에 만료되는 automation-bot 사용자의 토큰을 생성하려면: 

    user = User.find_by_username('automation-bot')
token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now)
token.set_token('token-string-here123')
token.save!

이 코드는 Rails runner를 사용하여 한 줄의 셸 명령으로 줄일 수 있습니다: 

sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"

프로그래밍 방식으로 개인 액세스 토큰 폐기

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

테스트나 자동화의 일환으로 개인 액세스 토큰을 프로그래밍 방식으로 폐기할 수 있습니다.

필수 조건:

토큰을 프로그래밍 방식으로 폐기하려면:

  1. Rails 콘솔을 엽니다: 

    sudo gitlab-rails console

  2. token-string-here123을 폐기하려면 다음 명령을 실행합니다: 

    token = PersonalAccessToken.find_by_token('token-string-here123')
token.revoke!

이 코드는 Rails runner를 사용하여 한 줄의 셸 명령으로 줄일 수 있습니다: 

sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"

개인 액세스 토큰을 사용하여 저장소 복제

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

SSH가 비활성화된 경우 저장소를 복제하려면 다음 명령을 실행하여 개인 액세스 토큰을 사용하여 복제합니다: 

git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git

이 방법은 개인 액세스 토큰을 bash 히스토리에 저장합니다. 이를 피하려면 다음 명령을 실행하세요: 

git clone https://<username>@gitlab.com/gitlab-org/gitlab.git

clone 명령어에서의 username:

  • 어떠한 문자열 값이어도 무방합니다.
  • 빈 문자열이 아니어야 합니다.

인증에 의존하는 자동화 파이프라인을 설정하는 경우 이를 기억하세요.

문제 해결

개인 액세스 토큰 취소 해제

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

개인 액세스 토큰이 실수로 취소된 경우, 관리자는 해당 토큰을 취소 해제할 수 있습니다. 기본적으로 매일 취소된 토큰을 시스템 시간의 오전 1시에 삭제하는 작업이 실행됩니다.

경고: 다음 명령을 실행하면 데이터가 직접 변경됩니다. 이것은 올바르게 수행되지 않거나 올바른 조건에서 실행되지 않으면 손상을 초래할 수 있습니다. 이러한 명령을 먼저 테스트 환경에서 실행하고, 백업된 인스턴스가 복원 준비 상태에 있어야 합니다.

  1. 레일스 콘솔을 엽니다.

  2. 토큰을 취소 해제합니다: 

    token = PersonalAccessToken.find_by_token('<token_string>')
token.update!(revoked:false)

    예를들어, token-string-here123를 취소 해제하려면: 

    token = PersonalAccessToken.find_by_token('token-string-here123')
token.update!(revoked:false)

개인 액세스 토큰의 대안

HTTPS를 통한 Git의 대안으로 OAuth 자격 증명 도우미를 사용할 수 있습니다.