InfoGrab DocsInfoGrab Docs

세분화된 개인 액세스 토큰

요약

세분화된 개인 액세스 토큰은 사용자가 정의한 리소스와 권한으로 범위가 제한됩니다. 세분화된 개인 액세스 토큰을 생성하려면 다음과 같이 합니다. 개인 액세스 토큰이 표시됩니다. 세분화된 개인 액세스 토큰으로 보내는 모든 API 요청은 두 가지 검사를 통과해야 합니다.

히스토리
  • GitLab 18.10에서 베타로 도입되었습니다.
  • GitLab 19.2에서 일반 공급되었습니다.
  • GitLab 19.6에서 기능 플래그 granular_personal_access_tokens가 제거되었습니다.

세분화된 개인 액세스 토큰은 사용자가 정의한 리소스와 권한으로 범위가 제한됩니다. 토큰을 생성할 때 다음 속성을 정의합니다.

  • 리소스: API 작업의 모음입니다. 리소스는 더 큰 경계(Group and project, User, Global)로 묶입니다.
  • 권한: 토큰이 리소스에 대해 수행할 수 있는 구체적인 작업입니다. 일반적으로 생성, 읽기, 업데이트, 삭제 작업에 해당합니다.

세분화된 개인 액세스 토큰 생성#

세분화된 개인 액세스 토큰을 생성하려면 다음과 같이 합니다.

  1. 오른쪽 상단 모서리에서 아바타를 선택합니다.
  2. Edit profile을 선택합니다.
  3. 왼쪽 사이드바에서 Access > Personal access tokens를 선택합니다.
  4. Generate token 드롭다운 목록에서 Fine-grained token을 선택합니다.
  5. Name과 Description 필드를 작성합니다.
  6. Expiration date 텍스트 상자에 토큰의 만료일을 입력합니다.
    • 토큰은 해당 날짜의 UTC 자정에 만료됩니다.
    • 날짜를 입력하지 않으면 만료일은 오늘로부터 365일 뒤로 설정됩니다.
    • 기본적으로 만료일은 오늘로부터 365일을 넘을 수 없습니다. GitLab 17.6 이상에서는 관리자가 액세스 토큰의 최대 수명을 수정할 수 있습니다.
  7. 그룹 또는 프로젝트 리소스를 추가하려면 Group and project access에서 옵션을 선택합니다.
  8. Add resource permissions에서 다음을 수행합니다.
    1. Group and project, User, Global 탭으로 경계별로 리소스를 필터링합니다.
    2. 왼쪽 패널에서 리소스를 하나 이상 선택합니다.
    3. 오른쪽 패널에서 각 리소스에 대해 사용 가능한 권한을 선택합니다.
  9. Generate token을 선택합니다.

개인 액세스 토큰이 표시됩니다. 개인 액세스 토큰을 안전한 곳에 저장합니다. 페이지를 벗어나거나 새로 고치면 다시 볼 수 없습니다.

세분화된 토큰이 각 요청을 인가하는 방식#

세분화된 개인 액세스 토큰으로 보내는 모든 API 요청은 두 가지 검사를 통과해야 합니다. 다음 두 가지가 모두 참이어야 합니다.

  • 토큰에 요청 경로의 리소스에 대한 해당 작업의 권한이 있습니다.
  • 토큰 소유자인 사용자가 해당 작업을 수행할 수 있습니다.

토큰 검사는 토큰이 어떤 API 작업을 어떤 리소스에 대해 호출할 수 있는지를 제어합니다. 이 검사를 통과한 뒤에는 사용자 본인의 액세스 권한이 작업의 허용 여부를 결정합니다.

sudo로 사용자 가장#

관리자는 REST API의 sudo 파라미터로 다른 사용자를 가장할 수 있는 세분화된 개인 액세스 토큰을 생성할 수 있습니다.

sudo 기능이 있는 토큰은 관리자만 생성할 수 있습니다. 관리자가 아닌 사용자가 생성하려고 하면 오류가 발생합니다.

세분화된 토큰은 가장하는 동안에도 자체 권한을 계속 적용합니다. 토큰은 다음 두 가지가 모두 참일 때만 작업을 수행할 수 있습니다.

  • 가장된 사용자가 해당 작업을 수행할 수 있습니다.
  • 토큰에 해당 작업을 허용하는 권한이 있습니다.

이 동작은 sudo 스코프가 있는 기존 개인 액세스 토큰과 다릅니다. 기존 토큰은 가장된 사용자로서 모든 작업을 수행할 수 있습니다.

Warning

sudo 기능이 있는 토큰은 모든 사용자로서 작동할 수 있습니다. 권한과 경계를 필요한 최소한으로 제한하고 안전하게 보관합니다.

사용 가능한 세분화된 권한#

세분화된 개인 액세스 토큰이 사용할 수 있는 권한은 토큰이 호출하는 엔드포인트에 따라 달라집니다.

세분화된 개인 액세스 토큰 적용#

히스토리
  • GitLab 18.11에서 granular_personal_access_tokens_enforcement와 granular_personal_access_tokens_enforcement_saas라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.2에서 GitLab Self-Managed에 일반 공급되었습니다.
  • GitLab 19.6에서 기능 플래그 granular_personal_access_tokens_enforcement가 제거되었습니다.
  • 최상위 그룹 적용이 GitLab 19.6에서 GitLab Self-Managed와 GitLab Dedicated에서 사용할 수 있게 되었습니다. 기능 플래그 granular_personal_access_tokens_enforcement_saas가 제거되었습니다.

지정한 적용 날짜 이후에 사용자가 세분화된 개인 액세스 토큰을 사용하도록 요구할 수 있습니다. 이 날짜 이후에도 기존 개인 액세스 토큰은 사용자 프로필에 계속 나열되지만 리소스에 액세스하는 데 사용할 수 없습니다.

세분화된 토큰은 다음과 같이 적용할 수 있습니다.

  • 최상위 그룹에 적용합니다. 그룹의 하위 그룹과 프로젝트가 적용 설정을 상속합니다.
  • GitLab Self-Managed에서는 전체 인스턴스에 적용합니다.

적용은 서비스 계정, 그룹 액세스 토큰, 프로젝트 액세스 토큰의 토큰에는 적용되지 않습니다. 이러한 토큰은 적용 날짜 이후에도 계속 작동하며, 계속 생성하고 교체할 수 있습니다.

최상위 그룹에 세분화된 토큰 적용#

사전 요구 사항:

  • 최상위 그룹에 대한 Owner 권한이 있어야 합니다.

적용은 그룹과 그 하위 그룹 및 프로젝트에 적용되며, 적용 날짜 이후 기존 개인 액세스 토큰이 해당 리소스에 액세스하는 것을 차단합니다. 사용자는 여전히 기존 토큰을 생성할 수 있지만, 해당 토큰은 그룹의 적용된 리소스에 액세스할 수 없습니다.

세분화된 토큰은 최상위 그룹에만 적용할 수 있습니다.

최상위 그룹에 세분화된 개인 액세스 토큰을 적용하려면 다음과 같이 합니다.

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 그룹을 찾습니다.
  2. Settings > General을 선택합니다.
  3. Permissions and group features를 확장합니다.
  4. Require fine-grained personal access tokens after a specific date를 선택합니다.
  5. 미래의 적용 날짜를 입력합니다. 적용 날짜는 협정 세계시(UTC)입니다.
  6. Save changes를 선택합니다.

적용 날짜 이후 사용자가 기존 토큰으로 최상위 그룹, 하위 그룹 또는 프로젝트의 리소스에 액세스하려고 하면 오류가 발생합니다. 이 오류에는 세분화된 토큰에 필요한 리소스 경계와 권한이 나열됩니다. 예를 들면 다음과 같습니다.

Access denied: This operation requires a fine-grained personal access token with the following project permissions: [Project: Read].

GitLab Self-Managed에서 세분화된 토큰 적용#

사전 요구 사항:

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

GitLab Self-Managed에서는 적용이 전체 인스턴스에 적용되며, 적용 날짜 이후 사용자가 기존 개인 액세스 토큰을 생성하거나 교체하지 못하게 합니다. 사용자는 세분화된 토큰만 생성할 수 있습니다. 기존 토큰은 만료될 때까지 계속 작동합니다.

인스턴스에 세분화된 개인 액세스 토큰을 적용하려면 다음과 같이 합니다.

  1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
  2. Settings > General을 선택합니다.
  3. Account and limit를 확장합니다.
  4. Require fine-grained personal access tokens after a specific date를 선택합니다.
  5. Fine-grained personal access tokens enforcement date에 미래의 날짜를 입력합니다.
  6. Save changes를 선택합니다.

적용 날짜 이후 사용자가 기존 토큰을 생성하거나 교체하려고 하면 오류가 발생합니다.

세분화된 개인 액세스 토큰

GitLab v19.6
Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기

요약

세분화된 개인 액세스 토큰은 사용자가 정의한 리소스와 권한으로 범위가 제한됩니다. 세분화된 개인 액세스 토큰을 생성하려면 다음과 같이 합니다. 개인 액세스 토큰이 표시됩니다. 세분화된 개인 액세스 토큰으로 보내는 모든 API 요청은 두 가지 검사를 통과해야 합니다.

히스토리
  • GitLab 18.10에서 베타로 도입되었습니다.
  • GitLab 19.2에서 일반 공급되었습니다.
  • GitLab 19.6에서 기능 플래그 granular_personal_access_tokens가 제거되었습니다.

세분화된 개인 액세스 토큰은 사용자가 정의한 리소스와 권한으로 범위가 제한됩니다. 토큰을 생성할 때 다음 속성을 정의합니다.

  • 리소스: API 작업의 모음입니다. 리소스는 더 큰 경계(Group and project, User, Global)로 묶입니다.
  • 권한: 토큰이 리소스에 대해 수행할 수 있는 구체적인 작업입니다. 일반적으로 생성, 읽기, 업데이트, 삭제 작업에 해당합니다.

세분화된 개인 액세스 토큰 생성#

세분화된 개인 액세스 토큰을 생성하려면 다음과 같이 합니다.

  1. 오른쪽 상단 모서리에서 아바타를 선택합니다.
  2. Edit profile을 선택합니다.
  3. 왼쪽 사이드바에서 Access > Personal access tokens를 선택합니다.
  4. Generate token 드롭다운 목록에서 Fine-grained token을 선택합니다.
  5. Name과 Description 필드를 작성합니다.
  6. Expiration date 텍스트 상자에 토큰의 만료일을 입력합니다.
    • 토큰은 해당 날짜의 UTC 자정에 만료됩니다.
    • 날짜를 입력하지 않으면 만료일은 오늘로부터 365일 뒤로 설정됩니다.
    • 기본적으로 만료일은 오늘로부터 365일을 넘을 수 없습니다. GitLab 17.6 이상에서는 관리자가 액세스 토큰의 최대 수명을 수정할 수 있습니다.
  7. 그룹 또는 프로젝트 리소스를 추가하려면 Group and project access에서 옵션을 선택합니다.
  8. Add resource permissions에서 다음을 수행합니다.
    1. Group and project, User, Global 탭으로 경계별로 리소스를 필터링합니다.
    2. 왼쪽 패널에서 리소스를 하나 이상 선택합니다.
    3. 오른쪽 패널에서 각 리소스에 대해 사용 가능한 권한을 선택합니다.
  9. Generate token을 선택합니다.

개인 액세스 토큰이 표시됩니다. 개인 액세스 토큰을 안전한 곳에 저장합니다. 페이지를 벗어나거나 새로 고치면 다시 볼 수 없습니다.

세분화된 토큰이 각 요청을 인가하는 방식#

세분화된 개인 액세스 토큰으로 보내는 모든 API 요청은 두 가지 검사를 통과해야 합니다. 다음 두 가지가 모두 참이어야 합니다.

  • 토큰에 요청 경로의 리소스에 대한 해당 작업의 권한이 있습니다.
  • 토큰 소유자인 사용자가 해당 작업을 수행할 수 있습니다.

토큰 검사는 토큰이 어떤 API 작업을 어떤 리소스에 대해 호출할 수 있는지를 제어합니다. 이 검사를 통과한 뒤에는 사용자 본인의 액세스 권한이 작업의 허용 여부를 결정합니다.

sudo로 사용자 가장#

관리자는 REST API의 sudo 파라미터로 다른 사용자를 가장할 수 있는 세분화된 개인 액세스 토큰을 생성할 수 있습니다.

sudo 기능이 있는 토큰은 관리자만 생성할 수 있습니다. 관리자가 아닌 사용자가 생성하려고 하면 오류가 발생합니다.

세분화된 토큰은 가장하는 동안에도 자체 권한을 계속 적용합니다. 토큰은 다음 두 가지가 모두 참일 때만 작업을 수행할 수 있습니다.

  • 가장된 사용자가 해당 작업을 수행할 수 있습니다.
  • 토큰에 해당 작업을 허용하는 권한이 있습니다.

이 동작은 sudo 스코프가 있는 기존 개인 액세스 토큰과 다릅니다. 기존 토큰은 가장된 사용자로서 모든 작업을 수행할 수 있습니다.

Warning

sudo 기능이 있는 토큰은 모든 사용자로서 작동할 수 있습니다. 권한과 경계를 필요한 최소한으로 제한하고 안전하게 보관합니다.

사용 가능한 세분화된 권한#

세분화된 개인 액세스 토큰이 사용할 수 있는 권한은 토큰이 호출하는 엔드포인트에 따라 달라집니다.

세분화된 개인 액세스 토큰 적용#

히스토리
  • GitLab 18.11에서 granular_personal_access_tokens_enforcement와 granular_personal_access_tokens_enforcement_saas라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.2에서 GitLab Self-Managed에 일반 공급되었습니다.
  • GitLab 19.6에서 기능 플래그 granular_personal_access_tokens_enforcement가 제거되었습니다.
  • 최상위 그룹 적용이 GitLab 19.6에서 GitLab Self-Managed와 GitLab Dedicated에서 사용할 수 있게 되었습니다. 기능 플래그 granular_personal_access_tokens_enforcement_saas가 제거되었습니다.

지정한 적용 날짜 이후에 사용자가 세분화된 개인 액세스 토큰을 사용하도록 요구할 수 있습니다. 이 날짜 이후에도 기존 개인 액세스 토큰은 사용자 프로필에 계속 나열되지만 리소스에 액세스하는 데 사용할 수 없습니다.

세분화된 토큰은 다음과 같이 적용할 수 있습니다.

  • 최상위 그룹에 적용합니다. 그룹의 하위 그룹과 프로젝트가 적용 설정을 상속합니다.
  • GitLab Self-Managed에서는 전체 인스턴스에 적용합니다.

적용은 서비스 계정, 그룹 액세스 토큰, 프로젝트 액세스 토큰의 토큰에는 적용되지 않습니다. 이러한 토큰은 적용 날짜 이후에도 계속 작동하며, 계속 생성하고 교체할 수 있습니다.

최상위 그룹에 세분화된 토큰 적용#

사전 요구 사항:

  • 최상위 그룹에 대한 Owner 권한이 있어야 합니다.

적용은 그룹과 그 하위 그룹 및 프로젝트에 적용되며, 적용 날짜 이후 기존 개인 액세스 토큰이 해당 리소스에 액세스하는 것을 차단합니다. 사용자는 여전히 기존 토큰을 생성할 수 있지만, 해당 토큰은 그룹의 적용된 리소스에 액세스할 수 없습니다.

세분화된 토큰은 최상위 그룹에만 적용할 수 있습니다.

최상위 그룹에 세분화된 개인 액세스 토큰을 적용하려면 다음과 같이 합니다.

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 그룹을 찾습니다.
  2. Settings > General을 선택합니다.
  3. Permissions and group features를 확장합니다.
  4. Require fine-grained personal access tokens after a specific date를 선택합니다.
  5. 미래의 적용 날짜를 입력합니다. 적용 날짜는 협정 세계시(UTC)입니다.
  6. Save changes를 선택합니다.

적용 날짜 이후 사용자가 기존 토큰으로 최상위 그룹, 하위 그룹 또는 프로젝트의 리소스에 액세스하려고 하면 오류가 발생합니다. 이 오류에는 세분화된 토큰에 필요한 리소스 경계와 권한이 나열됩니다. 예를 들면 다음과 같습니다.

Access denied: This operation requires a fine-grained personal access token with the following project permissions: [Project: Read].

GitLab Self-Managed에서 세분화된 토큰 적용#

사전 요구 사항:

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

GitLab Self-Managed에서는 적용이 전체 인스턴스에 적용되며, 적용 날짜 이후 사용자가 기존 개인 액세스 토큰을 생성하거나 교체하지 못하게 합니다. 사용자는 세분화된 토큰만 생성할 수 있습니다. 기존 토큰은 만료될 때까지 계속 작동합니다.

인스턴스에 세분화된 개인 액세스 토큰을 적용하려면 다음과 같이 합니다.

  1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
  2. Settings > General을 선택합니다.
  3. Account and limit를 확장합니다.
  4. Require fine-grained personal access tokens after a specific date를 선택합니다.
  5. Fine-grained personal access tokens enforcement date에 미래의 날짜를 입력합니다.
  6. Save changes를 선택합니다.

적용 날짜 이후 사용자가 기존 토큰을 생성하거나 교체하려고 하면 오류가 발생합니다.