배경#

잡 토큰 권한을 사용하면 GitLab API 엔드포인트에 접근하는 CI/CD 잡 토큰에 대해 세분화된 접근 제어를 할 수 있습니다. 활성화되면, 잡 토큰은 프로젝트에 대해 허용된 작업만 수행할 수 있습니다.

과거에는 잡 토큰이 기본적으로 리소스에 대한 광범위한 접근을 제공했습니다. 잡 토큰에 대한 세분화된 권한이 도입됨에 따라, 최소 권한 원칙을 준수하면서 세분화된 접근 제어를 활성화할 수 있습니다.

이 주제에서는 새로운 잡 토큰 권한에 대한 요구 사항과 기여 가이드라인을 안내합니다.

요구 사항#

승인되기 전에, 모든 새로운 잡 토큰 권한은 다음을 충족해야 합니다.

• 옵트인 방식이며 기본적으로 비활성화되어야 합니다.

• GitLab 보안 팀의 검토를 완료해야 합니다.

  검토를 위해 @gitlab-com/gl-security/product-security/appsec를 태그하세요.

이러한 요구 사항은 새로운 권한을 통해 사용자가 보안 구성에 대한 명시적인 제어를 유지하고, 의도하지 않은 권한 상승을 방지하며, 최소 권한 원칙을 준수하도록 보장합니다.

잡 토큰 권한 추가#

잡 토큰 권한은 여러 위치에 정의되어 있습니다. 새로운 권한을 추가할 때는 다음 파일이 업데이트되었는지 확인하세요.

• 백엔드 권한 정의: 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 엔드포인트 추가#

라우트 설정#

API 엔드포인트에 잡 토큰 정책 지원을 추가하려면, 두 가지 라우트 설정을 구성해야 합니다.

route_setting :authentication#

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

매개변수:

• job_token_allowed: true - CI/CD 잡 토큰이 이 엔드포인트에 대해 인증할 수 있도록 활성화합니다.

route_setting :authorization#

이 설정은 잡 토큰 접근에 대한 권한 수준과 접근 제어를 정의합니다.

매개변수:

• job_token_policies: 필요한 권한 수준입니다. 사용 가능한 정책은 lib/ci/job_token/policies.rb에 나열되어 있습니다.

• allow_public_access_for_enabled_project_features: 선택 사항. 프로젝트 기능의 표시 설정에 따라 접근을 허용합니다. 공개 접근 구성을 참고하세요.

사용 예시#

이 예시는 잡 토큰 정책의 repository 리소스에 대해 tags API 엔드포인트 지원을 추가하는 방법을 보여줍니다.

# In lib/api/tags.rb

resource :projects do
  # Enable job token authentication for this endpoint
  route_setting :authentication, job_token_allowed: true
  # Require the `read_repository` policy for reading tags
  route_setting :authorization, job_token_policies: :read_repository,
    allow_public_access_for_enabled_project_features: :repository
  get ':id/repository/tags' do
    # ... existing endpoint implementation
  end

  # Enable job token authentication for this endpoint
  route_setting :authentication, job_token_allowed: true
  # Require the `admin_repository` policy for creating tags
  route_setting :authorization, job_token_policies: :admin_repository
  post ':id/repository/tags' do
    # ... existing endpoint implementation
  end
end

주요 고려 사항#

권한 수준 선택#

작업에 따라 적절한 권한 수준을 선택하세요.

• 읽기 작업(GET 요청): :read_* 권한을 사용합니다.

• 쓰기/삭제 작업(POST, PUT, DELETE 요청): :admin_* 권한을 사용합니다.

공개 접근 구성#

allow_public_access_for_enabled_project_features 매개변수는 다음 경우에 잡 토큰이 엔드포인트에 접근할 수 있도록 허용합니다.

• 프로젝트에 적절한 표시 설정이 있습니다.

• 프로젝트 기능이 활성화되어 있습니다.

• 프로젝트 기능에 적절한 표시 설정이 있습니다.

• 리소스에 대해 잡 토큰 권한이 명시적으로 구성되지 않았습니다.

이는 하위 호환성을 제공하는 동시에, 프로젝트 기능이 공개적으로 접근 가능하지 않을 때 세분화된 제어를 가능하게 합니다.

테스트#

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

사용법#

필요한 매개변수와 함께 공유 예시를 포함하여 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

  # Your other endpoint-specific tests...
end

매개변수#

공유 예시는 다음 매개변수를 사용합니다.

• 적용되어야 하는 잡 토큰 정책(예: :read_repository)

• allow_public_access_for_enabled_project_features - (선택 사항) 엔드포인트가 제어하는 프로젝트 기능(예: :repository)

• expected_success_status - (선택 사항) 요청의 예상 성공 상태(기본값: :success)

공유 예시가 테스트하는 항목#

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

• 접근 허용: 접근하는 프로젝트에 필요한 권한이 구성된 경우, 잡 토큰이 엔드포인트에 접근할 수 있습니다.

• 접근 거부: 접근하는 프로젝트에 필요한 권한이 구성되지 않은 경우, 잡 토큰이 엔드포인트에 접근할 수 없습니다.

• 공개 접근 폴백: 권한이 구성되지 않았을 때의 allow_public_access_for_enabled_project_features 동작.

문서화#

새로운 API 엔드포인트에 대한 잡 토큰 지원을 추가한 후에는, CI/CD 잡 토큰에 대한 세분화된 권한 문서를 업데이트해야 합니다. 다음 명령을 실행하여 이 주제를 다시 생성하세요.

bundle exec rake ci:job_tokens:compile_docs