Delegating Administration

In some medium to large scale organizations, roles and responsibilities in software management and maintenance are distinct and well established. Because of the larger employee base and increased volume of work per area, tasks are separated and delegated to employees with specific expertise and understanding in a single area. For instance, some people may be in charge of the system administration, some of the security configuration, and others of the software configuration. While this separation of duties is necessary for medium to larger organizations to thrive, it can create complications when attempting to assign permissions securely and efficiently.

To reflect the needs of medium to larger organizations, two new permissions have been introduced with Jenkins v2.222 which enable a CloudBees CI administrator to delegate some parts of administration to a user without having to grant them the powerful Overall/Administrator permission.

The two new permissions include:

Overall/Manage: safely grant a user the ability to manage a subset of CloudBees CI configuration options.
Overall/SystemRead: grant a user the ability to view most of CloudBees CI configuration options, but in read only mode.

These new permissions are currently “Experimental” and disabled by default. When using the Role-based matrix authorization strategy in CloudBees CI, the administrator can grant a user/group the Overall/Manage and/or Overall/SystemRead permission to enable this functionality.

See JEP-223: "Manage" permission for managing non-security aspects of a Jenkins instance and JEP-224: Readonly system configuration, for more information.

Overall/Manage

The Overall/Manage permission allows a user to modify non-security related configuration settings. Examples of non-security settings include project naming restrictions, the system message, updating a CasC bundle, and managing nodes/clouds. Security related configuration, which is not accessible to a user with the Overall/Manage permission, includes items such as the script console, changing the security realm, and managing plugins.

Being able to delegate the ability to modify non-security related configuration settings is valuable, for instance in the case of a large enterprise environment where team leads are in charge of their team’s controller, but should not have the same admin access as the overall enterprise admin.

Figure 1. Top-level configuration settings available to a user with Overall/Manage

Overall/System Read

The Overall/System Read permission gives the user the ability to view, but not modify, the configuration of a CloudBees CI instance, including logs and monitoring information. There are a number of situations where being able to view the configuration is very valuable, such as:

To allow non-administrator users to see what configuration options are available to a plugin.

Given the increased use of Configuration as Code, a lot of CloudBees CI instances are fully managed as code; therefore, changes are not allowed through the UI. In this situation you cannot know when new plugin versions are available, unless you have the Overall/Administer permission.
To allow non-administrator users to debug issues with their builds easier.

In other words, given a CloudBees CI error message in a build the user can check which plugins are installed, and the version of the plugin. This situation allows the user to solve their issue themselves and makes it easier for the user to report an issue with a plugin directly to the maintainers.

A user with the Overall/SystemRead permission will notice some UX abnormalities, such as form fields being shown as disabled. Additionally, some fields will appear to be editable but there are no Save or Apply buttons, which prevent those changes from being persisted.

Enabling the new permissions

The new permissions are not enabled by default and must be manually enabled to use them in your instance.

Overall/Manage

To enable the Overall/Manage permission, do one of the following:

Install the Overall/Manage permission enabler plugin, which enables the new permission by default.
Pass the system property jenkins.security.ManagePermission=true when starting CloudBees CI.
```
java -Djenkins.security.ManagePermission=true -jar jenkins.war▼
```
Use the script console to set the system property.
```
Jenkins.MANAGE.setEnabled(true)▼
```
This setting will be lost after restarting Jenkins.

Overall/System Read

To enable the Overall/System Read permission, do one of the following:

Install the Extended Read Permission plugin, which enables the new permission by default
Pass the system property jenkins.security.SystemReadPermission=true when starting Jenkins
```
java -Djenkins.security.SystemReadPermission=true -jar jenkins.war▼
```
Use the script console to set the system property.
```
Jenkins.SYSTEM_READ.setEnabled(true)▼
```
This setting will be lost after restarting CloudBees CI.

Configuring the new permissions

Once the new permissions are enabled, you can assign them to a user or group when using Role-based matrix authorization as your Global Security Authorization Strategy provided by the CloudBees Role-Based Access Control plugin.

For the Overall/Manage permission to be functional, it must be assigned with the Overall/Read permission as illustrated in the image above.

It is possible to give both Overall/Manage and Overall/System Read permissions to the same user/group, allowing that user to view the CloudBees CI configuration allowed by Overall/System Read, but only persist changes to those things specifically allowed by Overall/Manage. In some cases, there will be form fields that appear editable, but are not currently allowed to be changed by a user with Overall/Manage. Attempts to save such settings will be safely ignored.

Modern Cloud Platforms

The following content applies only to CloudBees CI on modern cloud platforms.

Using the Overall/Manage permission with Teams

The Overall/Manage permission is not included in the Team roles created by default (Team Admin, Team Member and Team Guest).

It is necessary to create a custom role (or use one previously created), and add the Overall/Manage permission to it.

In the following examples, the cli script is a simplification for the whole Jenkins CLI command. See Jenkins CLI tool for more information.

Prerequisites

Overall/Manage permission is enabled

To add the Overall/Manage permission to a custom role:

Retrieve the name of the team controller where you want to apply the permission using the following Jenkins CLI command: cli teams

Sample output

{
    "data": [
        {
            "displayName": "A Team",
            "name": "YOUR_TEAM_NAME",
            "status": {
      		            "team": "READY"
            },
            "provisioningRecipe": "basic"
        }
    ],
    "version": "1"
}▼

Create a custom role which you will assign the Overall/Manage permission using the following Jenkins CLI command: cli team-roles YOUR_TEAM_NAME --add ROLE_OVERALL_MANAGE --display 'Team Overall/Manage'
Sample output
```
{
   "version":"1",
   "data":{
      "id":"YOUR_TEAM_NAME",
      "message":"Role [ROLE_OVERALL_MANAGE] was added to the team",
      "status":"success"
   }
}▼
```
Assign the Overall/Manage permission to your custom role using the following Jenkins CLI command: cli team-permissions YOUR_TEAM_NAME ROLE_OVERALL_MANAGE --add jenkins.model.Jenkins.Manage --type jenkins
Sample output
```
{
  "version": "1",
  "data": {
	    "id": "ROLE_OVERALL_MANAGE",
    "message": "Permission added correctly",
    "status": "success"
  }
}▼
```

To configure all of the permissions of the role using a JSON input:

Create a "team-overall-manage-permissions.json" file with the following content:

{
   "data":{
      "jenkinsInstancePermissions":[
        "hudson.model.Hudson.Read",
        "hudson.model.Hudson.Manage",
        "hudson.model.Item.Read",
        "hudson.model.Item.Configure",
        "hudson.model.Item.Create",
      ],
      "role": "ROLE_OVERALL_MANAGE",
      "teamPermissions":[
        "hudson.model.Item.Read",
        "hudson.model.Item.Configure",
        "hudson.model.Item.Create"
      ]
   },
   "version":"1"
}

+ NOTE: The additional permissions to "jenkins.model.Jenkins.Manage" are added as examples of permissions a team may want to add. Your team may need different permissions depending on your needs.

Run the following Jenkins CLI command: cli team-permissions YOUR_TEAM_NAME ROLE_OVERALL_MANAGE --put < team-overall-manage-permissions.json
Sample output
```
{
  "version": "1",
  "data": {
    "id": "ROLE_OVERALL_MANAGE",
    "message": "Permissions set correctly",
    "status": "success"
  }
}▼
```

(Optional) Check that the new permissions were saved successfully by running the following Jenkins CLI command: cli team-permissions YOUR_TEAM_NAME ROLE_OVERALL_MANAGE

Sample output

{
  "version": "1",
  "data": {
    "role": "ROLE_OVERALL_MANAGE",
    "jenkinsInstancePermissions": [
      "jenkins.model.Jenkins.Read",
      "jenkins.model.Jenkins.Manage",
      "hudson.model.Item.Read",
      "hudson.model.Item.Configure",
      "hudson.model.Item.Create"
    ],
    "teamPermissions": [
      "hudson.model.Item.Read",
      "hudson.model.Item.Configure",
      "hudson.model.Item.Create"
    ]
  }
}▼