배경#

Job token 권한은 GitLab API 엔드포인트에 접근하는 CI/CD job token에 대한 세밀한 접근 제어를 허용합니다. 활성화되면 job token은 프로젝트에 허용된 작업만 수행할 수 있습니다.

역사적으로 job token은 기본적으로 리소스에 대한 광범위한 접근을 제공해왔습니다. Job token에 대한 세밀한 권한의 도입으로 최소 권한 원칙을 준수하면서 세분화된 접근 제어를 활성화할 수 있습니다.

이 항목은 새 job token 권한에 대한 요구 사항과 기여 가이드라인을 제공합니다.

요구 사항#

수락되기 전에 모든 새 job token 권한은 다음 조건을 충족해야 합니다:

• 옵트인 방식이며 기본적으로 비활성화되어야 합니다.
• GitLab 보안 팀의 검토를 완료해야 합니다.
  • 검토를 위해 @gitlab-com/gl-security/product-security/appsec 태그를 지정합니다.

이 요구 사항은 새 권한이 사용자가 보안 구성에 대한 명시적인 제어를 유지하고 의도하지 않은 권한 에스컬레이션을 방지하며 최소 권한 원칙을 준수하도록 합니다.

Job token 권한 추가#

Job token 권한은 여러 위치에 정의됩니다. 새 권한을 추가할 때 다음 파일들이 업데이트되어야 합니다:

• 백엔드 권한 정의: lib/ci/job_token/policies.rb - 사용 가능한 권한 나열.
• JSON 스키마 유효성 검사: app/validators/json_schemas/ci_job_token_policies.json - Ci::JobToken::GroupScopeLink 및 Ci::JobToken::ProjectScopeLink 모델의 job_token_policies 속성에 대한 유효성 검사 스키마 정의.
• 프론트엔드 상수: app/assets/javascripts/token_access/constants.js - UI에 대한 권한 정의 나열.

API 엔드포인트를 job token 권한 스코프에 추가#

Route 설정#

API 엔드포인트에 job token 정책 지원을 추가하려면 두 가지 route 설정을 구성해야 합니다:

route_setting :authentication#

이 설정은 엔드포인트에 허용되는 인증 방법을 제어합니다.

매개변수:

• job_token_allowed: true - CI/CD job token이 이 엔드포인트에 대해 인증하도록 허용합니다.

route_setting :authorization#

이 설정은 job token 접근에 대한 권한 수준 및 접근 제어를 정의합니다.

매개변수:

• job_token_policies: 필요한 권한 수준. 사용 가능한 정책은 lib/ci/job_token/policies.rb에 나열되어 있습니다.
• allow_public_access_for_enabled_project_features: 선택 사항. 프로젝트 기능의 가시성 설정에 따라 접근을 허용합니다. 공개 접근 구성을 참조하세요.

사용 예시#

이 예시는 job token 정책의 repository 리소스에 tags API 엔드포인트에 대한 지원을 추가하는 방법을 보여줍니다:

# In lib/api/tags.rb

resource :projects do
  # 이 엔드포인트에 대한 job token 인증 활성화
  route_setting :authentication, job_token_allowed: true
  # 태그 읽기를 위해 `read_repository` 정책 요구
  route_setting :authorization, job_token_policies: :read_repository,
    allow_public_access_for_enabled_project_features: :repository
  get ':id/repository/tags' do
    # ... 기존 엔드포인트 구현
  end

  # 이 엔드포인트에 대한 job token 인증 활성화
  route_setting :authentication, job_token_allowed: true
  # 태그 생성을 위해 `admin_repository` 정책 요구
  route_setting :authorization, job_token_policies: :admin_repository
  post ':id/repository/tags' do
    # ... 기존 엔드포인트 구현
  end
end

주요 고려 사항#

권한 수준 선택#

작업에 따라 적절한 권한 수준을 선택합니다:

• 읽기 작업 (GET 요청): :read_* 권한 사용
• 쓰기/삭제 작업 (POST, PUT, DELETE 요청): :admin_* 권한 사용

공개 접근 구성#

allow_public_access_for_enabled_project_features 매개변수는 다음 경우에 job token이 엔드포인트에 접근할 수 있도록 합니다:

• 프로젝트에 적절한 가시성이 있는 경우.
• 프로젝트 기능이 활성화된 경우.
• 프로젝트 기능에 적절한 가시성이 있는 경우.
• 리소스에 대해 job token 권한이 명시적으로 구성되지 않은 경우.

이는 프로젝트 기능이 공개적으로 접근 가능하지 않을 때 세밀한 제어를 활성화하면서 하위 호환성을 제공합니다.

테스트#

API 엔드포인트에 대한 job token 권한을 구현할 때 'enforcing job token policies' 공유 RSpec 예제를 사용하여 인증 동작을 테스트합니다. 이 공유 예제는 모든 job token 정책 시나리오에 대한 포괄적인 커버리지를 제공합니다.

사용법#

필요한 매개변수와 함께 포함하여 API 엔드포인트 테스트에 공유 예제를 추가합니다:

describe 'GET /projects/:id/repository/tags' do
  let(:route) { "/projects/#{project.id}/repository/tags" }

  it_behaves_like 'enforcing job token policies', :read_repository,
    allow_public_access_for_enabled_project_features: :repository do
    let(:user) { developer }
    let(:request) do
      get api(route), params: { job_token: target_job.token }
    end
  end

  # 다른 엔드포인트별 테스트...
end

매개변수#

공유 예제는 다음 매개변수를 사용합니다:

• 적용해야 할 job token 정책 (예: :read_repository)
• allow_public_access_for_enabled_project_features - (선택 사항) 엔드포인트가 제어하는 프로젝트 기능 (예: :repository)
• expected_success_status - (선택 사항) 요청의 예상 성공 상태 (기본값: :success)

공유 예제가 테스트하는 것#

'enforcing job token policies' 공유 예제는 자동으로 다음을 테스트합니다:

1. 접근 허용: Job token이 접근된 프로젝트에 필요한 권한이 구성된 경우 엔드포인트에 접근할 수 있습니다.
2. 접근 거부: Job token이 접근된 프로젝트에 필요한 권한이 구성되지 않은 경우 엔드포인트에 접근할 수 없습니다.
3. 공개 접근 폴백: 권한이 구성되지 않았을 때 allow_public_access_for_enabled_project_features 동작.

문서#

새 API 엔드포인트에 대한 job token 지원을 추가한 후 CI/CD job token의 세밀한 권한 문서를 업데이트해야 합니다. 다음 명령을 실행하여 이 항목을 재생성합니다:

bundle exec rake ci:job_tokens:compile_docs