扩展 Jenkins 权限配置（基于角色的权限控制）
前置条件
确保已安装 Role-based Authorization Strategy 插件（上一节推荐的必装插件之一）。
安全域配置
进入 Manage Jenkins → Security → Configure Global Security。
安全域（Security Realm）
| 选项 | 说明 |
|---|---|
| Jenkins' own user database | 使用 Jenkins 内置用户系统（默认） |
| GitLab Authentication | 使用 GitLab 账号登录（需安装 GitLab 插件） |
| LDAP | 对接企业 LDAP 目录服务 |
| Active Directory | 对接企业 AD 域（需安装 Active Directory 插件） |
| SAML / OIDC | 对接 SSO 单点登录系统 |
授权策略（Authorization）
| 策略 | 说明 | 安全等级 |
|---|---|---|
| Anyone can do anything | 无权限控制 | 极危险，禁止使用 |
| Legacy mode | 兼容旧版本 | 不推荐 |
| Logged-in users can do anything | 登录用户拥有全部权限 | 低安全 |
| Matrix-based security | 矩阵式权限（细粒度） | 中等 |
| Role-Based Strategy | 基于角色的权限控制（推荐） | 高 |
选择 Role-Based Strategy 后点击 Apply 保存。
SSH 主机密钥验证
在 Security 配置页面的下方，找到 Git Host Key Verification Configuration：
| 选项 | 说明 | 推荐 |
|---|---|---|
| Accept first connection | 首次连接自动信任 | 推荐（Docker 环境下最方便） |
| Known hosts file | 使用已知主机文件 | 不推荐（Docker 环境配置复杂） |
Docker 环境下 Known hosts file 的配置路径位于 $JENKINS_HOME/.ssh/ 目录，容器化部署中管理不便，因此推荐 Accept first connection。
Jenkins 权限体系详解
在配置角色之前，需要理解 Jenkins 的完整权限模型。以下是各权限类别的说明：
Overall（全局权限）
| 权限 | 说明 | 风险等级 |
|---|---|---|
| Overall/Administer | 完全控制，包含脚本控制台、插件安装等 | 最高 |
| Overall/Manage | 部分管理功能（不含关键安全配置） | 高 |
| Overall/SystemRead | 只读访问全局配置 | 中 |
| Overall/Read | 基本访问权限，是其他操作的前提 | 低 |
注意：拥有 Overall/Administer 的用户可以执行任意代码（通过脚本控制台或安装插件），一旦被恶意获取应视为实例已被完全入侵，需要立即轮换所有密钥并重建实例。
Agent（代理/节点权限）
| 权限 | 说明 |
|---|---|
| Agent/Build | 在代理上运行构建任务 |
| Agent/Configure | 配置代理（高风险：可获得代理上的文件和凭据） |
| Agent/Connect | 连接代理或标记为在线 |
| Agent/Create | 创建新代理 |
| Agent/Delete | 删除代理 |
| Agent/Disconnect | 断开代理或标记为离线 |
Job（任务权限）
| 权限 | 说明 |
|---|---|
| Job/Build | 启动新构建 |
| Job/Cancel | 取消计划中或运行中的构建 |
| Job/Configure | 修改任务配置 |
| Job/Create | 创建新任务 |
| Job/Delete | 删除任务 |
| Job/Discover | 发现任务（低于 Read，用于重定向到登录页） |
| Job/Move | 移动任务到其他文件夹 |
| Job/Read | 查看任务详情 |
| Job/Workspace | 访问工作空间文件（含源码和构建产物） |
Run（构建运行权限）
| 权限 | 说明 |
|---|---|
| Run/Delete | 删除特定构建记录 |
| Run/Update | 更新构建描述和属性 |
| Run/Replay | 以编辑后的脚本重新运行 Pipeline |
View（视图权限）
| 权限 | 说明 |
|---|---|
| View/Configure | 修改视图配置 |
| View/Create | 创建新视图 |
| View/Delete | 删除视图 |
| View/Read | 查看视图 |
Credentials（凭据权限）
| 权限 | 说明 |
|---|---|
| Credentials/Create | 添加凭据 |
| Credentials/Delete | 删除凭据 |
| Credentials/ManageDomains | 管理凭据域 |
| Credentials/Update | 修改凭据 |
| Credentials/View | 查看凭据 |
角色管理完整步骤
配置完成后，Manage Jenkins 菜单下会多出 Manage and Assign Roles 选项。
第一步：创建角色（Manage Roles）
进入 Manage and Assign Roles → Manage Roles，页面分为三个区域：
1. Global Roles（全局角色）
全局角色对整个 Jenkins 实例生效，全局角色权限会覆盖 Item Roles 中的同名权限。例如，在全局角色中授予了 Job/Read，则无论 Item Roles 如何配置，该用户都能读取所有 Job。
| 角色名 | 权限配置 | 用途 |
|---|---|---|
admin | 全部权限 | 系统管理员 |
anonymous | Overall: Read | 未登录访客（只读） |
dev | Overall: Read + Job: Read + View: Read | 开发人员查看权限 |
builder | Overall: Read + Job: Read, Build, Cancel + Run: Update | 构建执行人员 |
viewer | Overall: Read + Job: Read + View: Read + Run: Read | 只读审计人员 |
2. Item Roles（项目角色）
项目角色通过正则表达式匹配具体的任务（Job）/ 文件夹。建议创建：
| 角色名 | Pattern | 权限 | 匹配范围 |
|---|---|---|---|
dev-role | test1.* | Job: Read, Build, View: Read | 匹配以 test1 开头的所有项目 |
folder-role | folder1/.* | Job: Read, Build, View: Read | 匹配 folder1 文件夹内的所有项目 |
qa-role | (?i)qa-.* | Job: Read, Build, Cancel, Workspace | 匹配以 qa- 开头的项目（大小写不敏感） |
Pattern 规则详解：
| 规则 | 示例 | 说明 |
|---|---|---|
| 基本匹配 | test1 | 精确匹配名为 test1 的项目 |
| 通配符 | test1.* | 匹配以 test1 开头的所有项目 |
| 大小写不敏感 | (?i)test.* | 匹配 test、Test、TEST 等 |
| 文件夹匹配 | folder1/.* | 匹配 folder1 文件夹内的所有内容 |
| 文件夹含自身 | (?i)folder($/|.*) | 同时匹配文件夹本身和内部项目 |
| 大小写敏感恢复 | (?i)folder/(?-i).* | 文件夹名大小写不敏感，内部项目名敏感 |
重要提示：要访问文件夹内的 Job，用户必须同时拥有对文件夹本身的访问权限。可以使用单一 Pattern
(?i)folder($|/.*)来同时匹配文件夹及其内部项目。
3. Agent Roles（代理角色）
代理角色控制用户对构建代理/节点的操作权限：
| 角色名 | Pattern | 权限 | 用途 |
|---|---|---|---|
agent-user | build-.* | Agent: Build, Connect | 允许在匹配的代理上运行构建 |
agent-admin | .* | Agent: 全部权限 | 代理管理员 |
角色创建示例
# 访客角色（anonymous）
Global Roles → 添加 "anonymous" → 勾选:
- Overall: Read
- Job: Read
- View: Read
# 开发角色（dev）
Item Roles → 添加 "dev-role" → Pattern: "test1.*" → 勾选:
- Job: Read
- Job: Build
- View: Read
# 文件夹角色（folder-role）
Item Roles → 添加 "folder-role" → Pattern: "(?i)folder1/.*" → 勾选:
- Job: Read
- Job: Build
- View: Read
# QA 角色
Item Roles → 添加 "qa-role" → Pattern: "(?i)qa-.*" → 勾选:
- Job: Read
- Job: Build
- Job: Cancel
- Job: Workspace
text
Permission Templates（权限模板）
当需要创建多个 Pattern 不同但权限相同的角色时，可以使用 Permission Templates 来简化管理：
- 在 Manage Roles 页面创建一个模板角色
- 新建 Item Role 时选择基于该模板
- 修改模板会自动更新所有关联角色的权限
第二步：分配角色（Assign Roles）
进入 Manage and Assign Roles → Assign Roles。
1. Global Roles Assignment
| 用户/组 | 分配的全局角色 |
|---|---|
admin | admin |
anonymous | anonymous |
dev-user | dev |
qa-user | viewer |
2. Item Roles Assignment
| 用户/组 | 分配的项目角色 |
|---|---|
anonymous | dev-role |
dev-user | dev-role, folder-role |
qa-user | qa-role |
3. Agent Roles Assignment
| 用户/组 | 分配的代理角色 |
|---|---|
dev-user | agent-user |
admin | agent-admin |
内置组：
authenticated（已登录用户）和anonymous（所有用户，含未登录）是两个内置组，可以直接在角色分配中使用。
第三步：验证权限
使用无痕模式或另一浏览器访问 Jenkins，以未登录状态验证：
- 访问 Dashboard，应只能看到被授权的项目
- 尝试创建任务，应被拒绝
- 在管理员账户中创建新任务后，刷新无痕窗口确认权限是否生效
- 验证 Pattern 匹配：创建匹配和不匹配 Pattern 的任务，确认只有匹配的可见
视图（View）与文件夹（Folder）
视图的作用
视图是一个过滤器，用于在 Dashboard 中筛选显示特定的任务。
Dashboard
├── 全部（All） → 显示所有任务
├── dev 视图 → 仅显示选中的任务（如 test1）
└── 自定义视图 → 按需筛选
text
创建视图：
- Dashboard 页面点击
+号 - 选择视图类型：
- 列表视图（List View）：手动选择要显示的任务
- 全局视图（My Views）：按规则自动筛选
- 我的视图（My View）：个人自定义视图
- 命名并选择要显示的任务
- 保存
文件夹的作用
文件夹是一个独立的命名空间，支持嵌套，可以实现项目分组。
Dashboard
├── folder1/
│ ├── test1 # 与顶层 test1 互不冲突
│ └── test2
├── folder2/
│ └── demo
└── test1 # 顶层任务
text
文件夹 vs 视图：
| 特性 | 视图（View） | 文件夹（Folder） |
|---|---|---|
| 本质 | 过滤器 | 独立命名空间 |
| 嵌套 | 不支持 | 支持 |
| 同名任务 | 不允许 | 允许（不同文件夹下） |
| 权限控制 | 通过 View Roles | 通过 Item Roles + Pattern |
| 凭据隔离 | 不支持 | 支持（文件夹级别凭据） |
基于文件夹的权限控制
当使用文件夹组织项目时，可以通过 Pattern 精确控制访问权限：
# 方式一：单一 Pattern 同时匹配文件夹和内容
角色名: folder-dev
Pattern: (?i)folder1($|/.*)
权限: Job: Read, Build, View: Read
# 方式二：分开匹配（需要不同权限时）
角色名: folder-read → Pattern: (?i)folder1 → Job: Read
角色名: folder-content → Pattern: (?i)folder1/.* → Job: Read, Build
# 分配给用户
Assign Roles → Item Roles → 将用户勾选到 folder-dev 角色
text
方式一适合文件夹和内部项目权限一致的场景；方式二适合需要区分文件夹本身和内部项目权限的场景。
完整权限配置流程图
1. 安装 Role-Based Strategy 插件
↓
2. Configure Global Security → 选择 Role-Based Strategy
↓
3. 配置 Git Host Key Verification → Accept first connection
↓
4. Manage Roles
├── Global Roles: 创建 admin / anonymous / dev 等角色
├── Item Roles: 创建项目角色 + Pattern
└── Agent Roles: 创建代理角色（可选）
↓
5. Assign Roles
├── Global Roles: 给用户分配全局角色
├── Item Roles: 给用户分配项目角色
└── Agent Roles: 给用户分配代理角色（可选）
↓
6. 验证（无痕模式 / 另一浏览器测试）
├── 确认访客只能看到被授权的项目
├── 确认操作权限正确（不能创建/删除等）
└── 确认 Pattern 匹配符合预期
text
其他权限控制方案
| 方案 | 插件 | 特点 | 适用场景 |
|---|---|---|---|
| Role-Based Strategy | role-strategy | 角色模板化，支持正则匹配 | 中大型团队，推荐 |
| Matrix-based Security | 内置 | 细粒度到每个权限，矩阵式配置 | 小团队 |
| GitLab Authentication | gitlab-oauth | 使用 GitLab 账号体系 | 已有 GitLab 的团队 |
| LDAP | ldap | 对接企业目录服务 | 企业集成 |
| Active Directory | active-directory | 对接 Windows AD 域 | Windows 企业环境 |
选择建议：
- 小团队（5人以内）：Matrix-based Security 即可满足
- 中大型团队：Role-Based Strategy（本节方案）
- 企业集成：LDAP 或 Active Directory + Role-Based Strategy 组合使用
安全最佳实践
1. 基本安全原则
- 禁止使用 "Anyone can do anything" 策略，即使是内部网络环境。Jenkins 2026 年安全公告（2026-03-18）明确指出该策略存在严重风险
- anonymous 用户只给最小权限（Read only），防止信息泄露
- 管理员账号与普通账号分开，日常操作使用普通账号
- 定期审计权限分配，移除离职人员的访问权限
- GitLab/LDAP 集成后，确保外部认证服务的安全性
2. 凭据安全
- 使用 Credentials Plugin 管理密钥、Token 和密码，绝不硬编码在 Pipeline 或配置文件中
- 利用文件夹级别凭据隔离不同项目的敏感信息
- 限制
Credentials/View权限，仅管理员和必要角色可查看凭据内容 - 定期轮换凭据，考虑集成外部密钥管理工具（如 HashiCorp Vault）
3. 代理安全
- 限制
Agent/Configure权限，该权限可导致用户获取代理上的所有文件和凭据 - 使用 TLS 加密代理与控制器之间的通信
- 避免使用 SYSTEM 用户运行构建（参见 Palo Alto Networks 关于默认构建授权的研究）
4. 脚本安全
- 限制 Script Console 的使用，仅管理员可访问
- 谨慎审批 Groovy 沙箱脚本，仅信任的管理员应审批待处理的脚本
- Pipeline 中使用
@NonCPS方法时注意安全影响
5. 插件与系统安全
- 及时更新 Jenkins 和插件，关注 Jenkins 安全公告（2026 年已发布多个 CVE）
- 启用 CSRF Protection（默认开启，不要关闭）
- 启用 Audit Trail Plugin 记录关键操作日志
- 考虑使用 Configuration as Code (JCasC) 插件统一管理权限配置，避免手动配置出错
6. 委托角色管理
对于大型组织，可以将角色管理权限委托给非管理员用户：
// 在 Script Console 中执行，启用委托权限
import com.michelin.cio.hudson.plugins.rolestrategy.RoleBasedAuthorizationStrategy
// 启用 Item Roles 管理权限
RoleBasedAuthorizationStrategy.ITEM_ROLES_ADMIN.setEnabled(true)
// 启用 Agent Roles 管理权限
RoleBasedAuthorizationStrategy.AGENT_ROLES_ADMIN.setEnabled(true)
groovy
或在启动参数中添加：
java -Dcom.michelin.cio.hudson.plugins.rolestrategy.RoleBasedAuthorizationStrategy.useItemAndAgentRoles=true \
-jar jenkins.war
bash
常见问题排查
| 问题 | 原因 | 解决方案 |
|---|---|---|
| anonymous 用户能看到所有 Job | Global Roles 中授予了 Job/Read | 移除 Global Roles 中的 Job/Read，改用 Item Roles 控制 |
| Pattern 匹配不生效 | 正则需要匹配完整名称 | 使用 test1.* 而不是 test1 来匹配以 test1 开头的所有项目 |
| 文件夹内项目不可见 | 缺少文件夹本身的访问权限 | 使用 (?i)folder($/|.*) 同时匹配文件夹和内容 |
| 创建任务权限异常 | Item 级别 Job/Create 需要 Role-Based Strategy 命名策略 | 在全局配置中设置 "Restrict project naming" 为 "Role-Based strategy" |
| 用户组不生效 | Security Realm 未提供组信息 | 确认 LDAP/AD 插件正确配置了组映射 |
参考资料
- Role-based Authorization Strategy - Jenkins Plugins
- Jenkins Permissions 官方文档
- Jenkins Managing Security
- Jenkins Security Advisory 2026-03-18
- Jenkins Security Advisory 2026-04-29
- Jenkins Security Best Practices (OneUptime, 2026)
- Jenkins Security Checklist 2026
- Implementing IAM on Jenkins Using the Role-Based Strategy Plugin
- How to Configure RBAC in Jenkins (Baeldung)
↑