Configuring Access Control

Overview

CloudBees Flow provides a comprehensive mechanism to control how individuals use the system.

  • Users must log in to view information or perform operations.

  • After you log in, system access is limited based on:

    • User name.

    • The groups to which that user belongs.

    • The permissions specified for various CloudBees Flow objects.

Access Control is the CloudBees Flow functionality that provides security for all system objects. After you are familiar with the following information describing the Access Control system, review the two examples, Basic ACL Setup and Team ACL Setup (at the end of this Help topic), which may provide guidance or insight for how you might setup enhanced CloudBees Flow security at your site.

Privileges

CloudBees Flow supports four privilege types for each object:

  • Read —Allows object contents to be viewed. In addition, users must have read privilege on the pipeline or release runtime in order to approve a manual task or gate rule.

  • Modify— Allows object contents (but not its permissions) to be changed.

  • Execute —If an object is a procedure or it contains procedures (for example, a project), this privilege allows object procedures to be invoked as part of a job. For resource objects, this privilege determines who can use this resource in job steps.

  • Change Permissions —Allows object permissions to be modified.

Users and Groups

CloudBees Flow uses account information from multiple sources. In most cases, the primary account information source is an external LDAP or Active Directory repository:

  • Both user and group information is retrieved from the repository

  • Local users and groups can be defined within CloudBees Flow

To view user and group information, and to modify local user and group information, click the Administration tab and select either the Users or Groups subtab. External account information cannot be modified from CloudBees Flow.

If the same user exists in multiple sources, only the highest priority name is used. A priority order is defined among external repositories, but local names have the highest priority. Thus, if you define a local user with the same name as an LDAP user, you will effectively mask the user in the LDAP account.

For local user accounts, only local groups are considered—group information from external repositories is not used. For accounts from a particular repository, groups from that repository are used along with local groups, but groups in other repositories are not considered.

In other words, you can define local groups in CloudBees Flow to supplement groups defined in external repositories. When you view information about users in CloudBees Flow, only relevant groups are shown. For example, when you view group information for a local user, only local groups are displayed.

Groups are managed by name only, without regard to source. If a particular group name exists in different repositories, there is no way to distinguish between these groups inside CloudBees Flow. Access given to one group is the same for any other group with the same name.

Special Users and Groups

The admin local user has special significance. If you are logged in as "admin," you automatically have all privileges on all objects, regardless of any other system settings. This privilege set is a fallback mechanism in the event too many privileges get removed for an object, leaving it unusable.

The admin account cannot be deleted.

If the admin account is missing, CloudBees Flow will recreate the account the next time it starts up with password "changeme."

The Everyone group is predefined by CloudBees Flow and cannot be deleted. Every user is automatically a member of the Everyone group.

For each project, CloudBees Flow uses the project name and automatically defines a user associated with that project, called the project principal. For example, the project principal for a project named "nightly builds" is " project: nightly builds " (notice that there are two spaces in this name)— this principal is used for jobs running under the project, as described in Access control and jobs .

Access Control Lists—allow and deny

Each CloudBees Flow object, such as a project, procedure, job, property sheet, workspace, schedule, or resource contains an access control list (ACL). Individual properties do not have their own access control, but instead use access control lists from their parent containers.

To view the access control list for an object, go to the web page displaying the object and click the Access Control link. An access control list can contain any number of entries— each entry names a particular user or group and indicates allow , deny , or is blank for each of the four privileges.

To determine whether a user can perform an operation on a particular object, CloudBees Flow determines which of the four privileges is required for that operation, then searches all access control entries that refer to that user or groups containing that user. To be allowed access, at least one of the matching entries must specify "allow" and none of the entries can be "deny." A "deny" entry overrides an "allow" entry in the same ACL.

Inheritance

If an object’s access control list does not indicate what to do for the user who is trying to access it, CloudBees Flow looks in the access control list for the object containing the target object, then its parent, and so on up to a top-level object covering the entire server. This mechanism is called inheritance .

For example, a nested property sheet on a procedure inherits access control information from its parent property sheet, the procedure, the project containing the procedure, and the server. When you view the object access control list, you also see inherited access control lists so you can trace the object’s inheritance chain.

When CloudBees Flow performs an access check on an object, it begins with the access control list for that object.

  • If a "deny" entry matches an entry in that list, access is denied.

  • If there is no "deny" entry, but a matching "allow" entry is found, access is allowed.

  • If there is no matching entry that specifies either "allow" or "deny," CloudBees Flow moves to the next access control list in the inheritance chain and repeats the process.

  • A matching entry in a lower-level access control list takes priority over entries in higher-level access control lists. If no matching entry in any list is found, access is denied.

Inheritance allows you to control access to a collection of objects because you can make changes in just one place. When new objects are created, their access control lists are empty, so all access control for the entire system is determined by the server-level list.

  • Typically, when a new project is created, you define an access control list for the project and allow everything in the project to inherit from the project.

  • If you do not define additional access control information in project components, all project access is determined by the project’s access control list.

In some situations you may want tight control over object access, so changes in parent objects do not affect access to the object or its children. To achieve this, you can "break inheritance," which means a particular object does not inherit from its ancestors. The CloudBees Flow web interface allows you to break and restore inheritance for any object on which you can change permissions. However, if you break an object’s inheritance, it affects all children of that object.

Additional Information about "deny"

If a user matches a deny rule, however indirectly, the user is denied access. Even if a specific ACL entry granting (for example) read access by username exists, a less specific deny ACL entry overrides that specific rule. Therefore, avoid "deny" rules if at all possible (especially to groups), or you may experience some unexpected permissions issues.

You can, however, enforce an implicit "deny" by allowing an object to fall off the end of the inheritance chain. This practice allows denial behavior without the risks associated with an explicit ACL entry to deny access.

If you break inheritance on an object with an empty access control list, the object will become completely inaccessible. You will not be able to restore inheritance because you no longer have the right to change permissions on that object. If this happens, you must contact your system administrator who can login as admin and restore inheritance.

Consider CloudBees Flow principals (actors) from two perspectives:

  • A running job or workflow runs using the project as the identity, so if a job requires special permissions you must use the project as the principal in the ACL entry.

  • Users and groups come into play when humans manipulate the GUI or execute ectool commands from the command line (or via a shell script) — basically anywhere that a script or human needs to log in to CloudBees Flow. Having logged in, a group and id exist, which can be used in ACL entries.

For example, consider a property that will store a build number. You can set an ACL that breaks inheritance (implicit deny), and then add an ACL entry granting permissions for the project to be able to increment the property value. This prevents humans from manipulating the build number but permits a running job to increment the build number at will.

NOTE:

  • When it is practical, a job will run with multiple identities—the project and the user that launched the job. You cannot, however rely on this behavior for security because jobs run from a schedule (such as CI jobs) and jobs started by a workflow do not have a user principal, just the project principals.

  • A job can have multiple project principals because it "accumulates" new project principals when it calls into another project’s subprocedure (and then releases the other project’s identity when the subprocedure returns). This makes is possible to create trusted libraries.

System Objects

A few special system objects contain access control lists related to overall CloudBees Flow system administration. These access control lists are available from the Administration > Server page. The system objects are:

  • Server— a CloudBees Flow system top-level object. Every other object in the system is contained in the server object and inherits access control information from the server object unless inheritance is broken.

  • Administration— Read permission allows access to the getStatus, getDatabaseConfiguration[s], getEmailConfig[s], and export (global) API functions.

    Modify permission allows access to the shutdown, setDatabaseConfiguration, createEmailConfig, deleteEmailConfig, modifyEmailConfig, and import (global) API functions.

    For Change Tracking, the Read , Modify , and Execute permissions allow you to revert changes to a tracked object and its tracked contents in the UI (see for more details) or access to the revert API function.

  • Artifacts — Read permission allows access to the getArtifact API functions. Modify permissions allows access to createArtifact and deleteArtifact functions.

  • Directory — Read permission allows access to the getUsers, getGroups, and getDirectoryProviders API functions.

    Modify permission allows access to the createUser, createGroup, deleteUser, deleteGroup, createDirectoryProvider, modifyDirectoryProvider, deleteDirectoryProvider, testDirectoryProvider, and moveDirectoryProvider API functions.

  • Email Configurations — Modify permission allows access to the createEmailConfig and deleteEmailConfig API functions.

  • Force Abort — Execute permission controls access to the --force flag on abortJob. By default, the ACL is created with Everyone: execute permission in addition to inheriting from the "Server". To force abort a job, the user must have execute permission on the job and execute permission on the forceAbort ACL.

  • Licensing— Read permission allows access to the getLicense[s] API functions. Modify permission allows access to the importLicenseData and deleteLicense API functions. Execute permission allows access to the getAdminLicense API function.

  • Logging— Modify permission allows access to the logMessage API function.

  • SSO Configuration— Modify permission allows access to the Kerberos configuration settings.

  • Personas— Modify permission allows access to the personas API functions.

  • Plugins— Modify permission allows access to the createPlugin, deletePlugin, installPlugin, uninstallPlugin, promotePlugin API functions, and the modifyPlugin API function requires modify permission on the target plugin. For getPlugin, Read permission is required on the target plugin.

  • Priority— Execute permission allows the user who launches a procedure (using the runProcedure API function) to raise the priority of the job.

  • Projects— Modify permission allows access to the createProject and deleteProject API functions.

  • Repositories— Read permission allows access to the getRepository API function. Modify permission allows access to the createRepository, deleteRepository, modifyRepository, and moveRepository API functions.

  • Resources— Modify permission allows access to the createReource and `deleteResource ` API functions.

  • Report Object Types— Modify permission allows access to the createReportObjectType, deleteReportObjectType, getReportObjectType, getReportObjectTypes, and modifyReportObjectType API functions.

  • DevOps Insight Server Configuration— Modify permission allows access to the DevOps Insight server configuration settings.

  • SearchFilters— Execute permission allows access to the SearchFilters settings.

  • Session— Execute permission allows access to the login API function.

  • Tags— Execute permission allows access to the tags API function.

  • Workspaces— Modify permission allows access to the createWorkspace and deleteWorkspace API functions.

  • ZoneAndGateways— Modify permission allows access to the `createZone ` and `deleteZone ` API functions. Modify permission also allows access to the `deleteResource ` API function when the resource belongs to a Gateway.

Access Control and Jobs

When a job executes, it usually needs to access objects in CloudBees Flow. For example, a job step command may refer to a parameter value, which is a property associated with the job object, or a step may invoke ectool to modify properties or any other CloudBees Flow state. This process leads to questions:

  • Under which username does the job execute?

Procedures always run under the project principal user ID for the project that contains the procedure. If a procedure invokes a subprocedure in another project, that subprocedure will run under its own project’s project principal and the project principal of its calling procedure. When a procedure is running under multiple project principals, its steps will perform any operations for which any one of its project principals allow.

  • How does CloudBees Flow initialize job permissions when the job starts?

This question pertains to job object permissions. When a job starts, CloudBees Flow sets full access control entries on the job for the project principal and the user who launched the job— assuming the job was launched by a user and not a schedule.

  • What permissions are needed to abort a job?

Aborting a job requires execute permission on the job. If a job is launched by a user, that user is given all privileges on the job. If a job is launched by a schedule, the schedule’s execute privileges are copied to the job.

The access control system determines whether jobs can be executed or not.

  • For a user to run a job without creating a schedule, the user must have execute permission on the top-level procedure being executed.

  • To create a schedule to run a procedure, a user must have modify permission for the project containing the schedule. After a schedule is created, no additional permissions are required to start jobs under the auspices of that schedule.

Examples for Increased Security

Initially, the Everyone group had Read and Execute permission on all CloudBees Flow objects by default. The following examples illustrate how you might customize CloudBees Flow default Access Control settings for your organization.

Make sure you are familiar with the Access Control system before making changes. Incorrectly setting ACLs can severely impact CloudBees Flow behavior.

Abbreviations used in the examples

A = Allow

I = Inherit (some places referred to as "Don’t Care")

D = Deny

Change Permission = Change

Example 1—Basic ACL Setup

This example illustrates how you might change Access Control defaults to set up a basic level of security. The easiest way to manage ACLs is by using different CloudBees Flow groups that allow users to perform specific roles.

For our example, we will create and use the groups called EC-administrator and EC-designer, and we will modify the default Everyone group. (When setting up your groups, you would choose any group names that suit your organization, but note that the "EC-" prefix is reserved for CloudBees use only.) This is how we want to define our groups:

  • EC-administrator group This group has most of the power and abilities of the ‘admin’ user login, but allows for more flexibility.

  • EC-designer group This role is more significant. Users in this group can create and modify most CloudBees Flow objects.

  • Everyone group This predefined group is used for people who only need to run CloudBees Flow procedures, and have no need to create or modify them.

As you begin to modify the Access Control system, note that the system has some project principal ACEs that should remain in place for correct system operation.

Server ACLs

The Server is the foundation for almost all ACL checks. Generally, every other object in the system inherits these privileges. For this basic ACL configuration we want to set Server ACLs this way:

TypeNameReadModifyExecuteChange

group

EC-administrator

A

A

A

A

group

Everyone

I

I

I

I

Custom Server Properties ACLs

An often overlooked ACL setting is Server Property Sheet. Allow the Everyone group Read permission on this object.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

System Object ACLs

There are 14 categories of System objects with ACLs.

1—Administration – allow the EC-designer group Read privileges.

TypeNameReadModifyExecuteChange

group

EC-designers

A

I

I

I

2—Artifacts – allow the EC-designer group Read privileges.

TypeNameReadModifyExecuteChange

group

EC-designers

A

A

I

I

group

Everyone

A

I

I

I

3—Directory – allow the Everyone group Read privileges.

TypeNameReadModifyExecuteChange

group

EC-designers

A

I

I

I

4—Email Configurations – allow the Everyone group Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

5—Force Abort —no changes needed for this category.

6—Logging— no changes needed for this category.

7—Licensing— no changes needed for this category.

8—Plugins— allow the Everyone group Read privilege.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

9—Priority— no changes needed for this category.

10—Projects— allow the Everyone group Read and Execute privileges, and the EC-designer group everything except Change privilege.

TypeNameReadModifyExecuteChange

group

EC-designers

A

A

A

I

group

Everyone

A

I

A

I

11—Repositories— allow the Everyone group Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

12—Resources— allow the Everyone group Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

13—Session— allow the Everyone group Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

I

I

A

I

14—Workspaces— allow the Everyone group to have Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

Sites that want a slightly more open system might consider granting the "EC-designers" group Modify access to Resources and Workspaces.

Plugin Project ACLs

Generally, you will want to allow the Everyone group Read privileges on every plugin you expect to use. (Each plugin has its own name, which is the project name also.)

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

Project ACLs

Next are special CloudBees projects, Default, EC-Utilities and EC-Examples.

Use caution when setting privileges on the EC-Utilities project. These are powerful procedures and some have their own ACL settings. Remember the ‘admin’ user will always be able to use these utilities. Allowing the EC-administrator group full privileges accomplishes the same goal for users in that group. We allow the Everyone group Read only privileges. This is a unique project because it does not inherit ACLs from anywhere else (for example, Server or Projects).

TypeNameReadModifyExecuteChange

group

EC-administrator

A

A

A

A

group

Everyone

A

I

I

I

Example 2—Team ACL Setup

Some organizations may want to have two or more different and separate teams use CloudBees Flow at the same time. In this example, people on one team have little knowledge about the other team who uses CloudBees Flow and no direct access to any objects used by the other team. Our "Team" example describes how to modify default CloudBees Flow Access Control settings to create a multi team security configuration using ACLs.

To divide your CloudBees Flow system for use by separate teams, you will want to create one or more separate Projects for each team. You may decide to share some projects across teams.

Create your teams (groups). For our example, we will begin with two teams, T1 and T2. Each team has a designer group and a user group. Using groups allows the flexibility to have a designer from one group work as a user in another group.

  • Create the EC-administrator group This group has most of the power and abilities of the ‘admin’ user login, but allows for more flexibility. Assigning people to the EC-administrator group allows better tracking of CloudBees Flow administrative activity.

  • Create two designer groups:T1-designer and T2-designer Members of the designer groups will have the ability to create and modify procedures and other CloudBees Flow objects for their team. A member of the designer group from one team will not be able to view or use the objects of the other team.

  • Create two user groups: T1-user and T2-user Members of the user groups will have the ability to run procedures that belong to their team. A member of the user group from one team will not be able to view or use objects that belong to the other team. who are not in any other group. This setup allows other users to access CloudBees Flow without exposing the work of any of the teams. A person not in a group for either team will not be able to see objects of either of the teams.

As you begin to modify the Access Control system, note that the system has some project principal ACEs that should remain in place for correct system operation.

Server ACLs

The Server is the foundation for almost all ACL checks. Almost all objects in the system inherit these privileges. For this basic Team configuration, we will set the Server ACLs this way:

TypeNameReadModifyExecuteChange

group

EC-administrator

A

A

A

A

group

Everyone

I

I

I

I

Custom Server Properties ACLs

An often overlooked ACL setting is Server Property Sheet. Allow the Everyone group Read permission on this object.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

System Object ACLs

There are 14 categories of System objects with ACLs.

1—Administration – allow both designer groups Read privileges.

TypeNameReadModifyExecuteChange

group

T1-designer

A

I

I

I

group

T2-designer

A

I

I

I

2—Artifacts – allow the Everyone group Read privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

3—Directory – allow the Everyone group Read privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

4—Email Configurations – allow the Everyone group Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

5—Force Abort— no changes needed for this category.

6—Logging —no changes needed for this category.

7—Licensing —no changes needed for this category.

8—Plugins —allow the Everyone group Read privilege. Generally, privileges set here will be inherited by all plugins.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

9—Priority —no changes needed for this category.

10—Projects —no changes needed for this category. Privileges for projects are now handled on a case by case basis.

11—Repositories – allow the Everyone group Read privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

12—Resources —allow the Everyone group Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

13—Session —allow the Everyone group Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

I

I

A

I

14—Workspaces —allow the Everyone group Read and Execute privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

Plugin Project ACLs

Generally, you will want to allow the Everyone group Read privileges on every plugin you expect to use. (Each plugin has its own name, which is also the project name.) Because you may want to use many plugins, you might want to use a script.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

ACLs for Existing Projects

Next are a few CloudBees projects, and two sample projects that can be seen and used by their respective team members only.

Project: EC-Examples

These are nice examples and we want to grant Everyone the ability to see and run them.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

Project: Default

Inherited settings will allow the EC-administrator group full privileges.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

Project: EC-Utilities

Use caution when setting privileges on the EC-Utilities project. These are powerful procedures and some have their own ACL settings.

Remember the ‘admin’ user will always be able to use these utilities. Allowing the EC-administrator group full privileges accomplishes the same goal for users in that group. We allow the Everyone group Read only privileges. This is a unique project because it does not inherit ACLs from anywhere else (for example, Server or Projects).

TypeNameReadModifyExecuteChange

group

EC-administrator

A

A

A

A

group

Everyone

A

I

I

I

Project: CloudBees

This project has one procedure and we want to grant everyone the ability to see it.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

I

I

ACLs for New Projects

Now we introduce the concept of ACL settings as they would be in a multiple team environment. For this example, we assume you have five projects being used by two teams in the following way.

  • Project-A used by Team1

  • Project-B used by Team1

  • Project-C used by Team2

  • Project-D used by Team2

  • Project-E used by Team1 and Team2

Project-A

This project is visible and usable only by CloudBees Flow users who are members of either the T1-user group or the T1-designer group. Notice that the designer group receives full permissions.

TypeNameReadModifyExecuteChange

group

T1-designer

A

A

A

A

group

T1-user

A

I

A

I

Project-B

This project is the same as Project-A.

TypeNameReadModifyExecuteChange

group

T1-designer

A

A

A

A

group

T1-user

A

I

A

I

Project-C

This project is visible and usable only by CloudBees Flow users who are members of either the T2-user group or the T2-designer group. Notice that the designer group receives full permissions.

TypeNameReadModifyExecuteChange

group

T2-designer

A

A

A

A

group

T2-user

A

I

A

I

Project-D

This project is the same as Project-C.

TypeNameReadModifyExecuteChange

group

T2-designer

A

A

A

A

group

T2-user

A

I

A

I

Project-E

This project is a superset that includes both teams.

TypeNameReadModifyExecuteChange

group

T1-designer

A

A

A

A

group

T1-user

A

I

A

I

group

T2-designer

A

A

A

A

group

T2-user

A

I

A

I

Enabling Same Team Subprocedures

To enable procedures in one project to use procedures in another project, one more step is necessary.

Add the project principals for both T1 projects to the T1-user group. In this case, these are called: “project: Project-A” and “project: Project-B”.

Add the project principals for both T2 projects to the T2-user group. In this case, these are called: “project: Project-C” and “project: Project-D”.

Optional: Restricting Resources and Workspaces by Team

Resource ACLs

Resource: local

Because each team will have dedicated resources, it is useful to keep one resource available for everyone to use.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

T1-resource

This resource is visible and usable only by CloudBees Flow users who are members of either the T1-user group or the T1-designer group. This resource also needs Execute permission for the project itself to allow it to run from a schedule.

TypeNameReadModifyExecuteChange

group

T1-designer

A

I

A

I

group

T1-user

A

I

A

I

T2-resource

This resource is visible and usable only by CloudBees Flow users who are members of either the T2-user group or the T2-designer group. This resource also needs Execute permission for the project itself to allow it to run from a schedule.

TypeNameReadModifyExecuteChange

group

EC-administrator

A

A

A

A

group

Everyone

I

I

I

I

Workspace ACLs

Workspace: default

Because there will be dedicated workspaces for each team, it is useful to keep one workspace available for Everyone to use.

TypeNameReadModifyExecuteChange

group

Everyone

A

I

A

I

T1-workspace

This workspace is visible and usable only by CloudBees Flow users who are members of either the T1-user group or the T1-designer group.

TypeNameReadModifyExecuteChange

group

T1-designer

A

I

A

I

group

T1-user

A

I

A

I

T2-workspace

This workspace is visible and usable only by CloudBees Flow users who are members of either the T2-user group or the T2-designer group.

TypeNameReadModifyExecuteChange

group

T2-designer

A

I

A

I

group

T2-user

A

I

A

I