Job token 权限开发指南

背景

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 schema 验证：app/validators/json_schemas/ci_job_token_policies.json - 定义 Ci::JobToken::GroupScopeLink 和 Ci::JobToken::ProjectScopeLink 模型的 job_token_policies 属性的验证 schema。
• 前端常量：app/assets/javascripts/token_access/constants.js - 列出 UI 的权限定义。

为 job token 权限范围添加 API 端点

路由设置

要为 API 端点添加 job token 策略支持，需要配置两个路由设置：

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: 可选。允许基于项目功能的可见性设置进行访问。参见 public access configuration。

使用示例

此示例展示如何为 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 权限时，使用共享的 RSpec 示例 'enforcing job token policies' 来测试授权行为。此共享示例为所有 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