Managing Security
Table of Contents
Jenkins is used everywhere from workstations on corporate intranets, to high-powered servers connected to the public internet. To safely support this wide spread of security and threat profiles, Jenkins offers many configuration options for enabling, editing, or disabling various security features.
As of Jenkins 2.0, many of the security options were enabled by default to ensure that Jenkins environments remained secure unless an administrator explicitly disabled certain protections.
This section will introduce the various security options available to a Jenkins administrator, explaining the protections offered, and trade-offs to disabling some of them.
Enabling Security
When the Enable Security checkbox is checked, which has been the default since Jenkins 2.0, users can log in with a username and password in order to perform operations not available to anonymous users. Which operations require users to log in depends on the chosen authorization strategy and its configuration; by default anonymous users have no permissions, and logged in users have full control. This checkbox should always be enabled for any non-local (test) Jenkins environment.
The Enable Security section of the web UI allows a Jenkins administrator to enable, configure, or disable key security features which apply to the entire Jenkins environment.
JNLP TCP Port
Jenkins uses a TCP port to communicate with agents launched via the JNLP protocol, such as Windows-based agents. As of Jenkins 2.0, by default this port is disabled.
For administrators wishing to use JNLP-based agents, the two port options are:
-
Random: The JNLP port is chosen random to avoid collisions on the Jenkins master. The downside to randomized JNLP ports is that they’re chosen during the boot of the Jenkins master, making it difficult to manage firewall rules allowing JNLP traffic.
-
Fixed: The JNLP port is chosen by the Jenkins administrator and is consistent across reboots of the Jenkins master. This makes it easier to manage firewall rules allowing JNLP-based agents to connect to the master.
Access Control
Access Control is the primary mechanism for securing a Jenkins environment against unauthorized usage. Two facets of configuration are necessary for configuring Access Control in Jenkins:
-
A Security Realm which informs the Jenkins environment how and where to pull user (or identity) information from. Also commonly known as "authentication."
-
Authorization configuration which informs the Jenkins environment as to which users and/or groups can access which aspects of Jenkins, and to what extent.
Using both the Security Realm and Authorization configurations it is possible to configure very relaxed or very rigid authentication and authorization schemes in Jenkins.
Additionally, some plugins such as the Role-based Authorization Strategy plugin can extend the Access Control capabilities of Jenkins to support even more nuanced authentication and authorization schemes.
Security Realm
By default Jenkins includes support for a few different Security Realms:
- Delegate to servlet container
-
For delegating authentication a servlet container running the Jenkins master, such as Jetty. If using this option, please consult the servlet container’s authentication documentation.
- Jenkins’ own user database
-
Use Jenkins’s own built-in user data store for authentication instead of delegating to an external system. This is enabled by default with new Jenkins 2.0 or later installations and is suitable for smaller environments.
- LDAP
-
Delegate all authentication to a configured LDAP server, including both users and groups. This option is more common for larger installations in organizations which already have configured an external identity provider such as LDAP. This also supports Active Directory installations.
|
This feature is provided by the LDAP plugin that may not be installed on your instance. |
- Unix user/group database
-
Delegates the authentication to the underlying Unix OS-level user database on the Jenkins master. This mode will also allow re-use of Unix groups for authorization. For example, Jenkins can be configured such that "Everyone in the
developersgroup has administrator access." To support this feature, Jenkins relies on PAM which may need to be configured external to the Jenkins environment.
|
Unix allows an user and a group to have the same name. In order to
disambiguate, use the |
Plugins can provide additional security realms which may be useful for incorporating Jenkins into existing identity systems, such as:
Authorization
The Security Realm, or authentication, indicates who can access the Jenkins environment. The other piece of the puzzle is Authorization, which indicates what they can access in the Jenkins environment. By default Jenkins supports a few different Authorization options:
- Anyone can do anything
-
Everyone gets full control of Jenkins, including anonymous users who haven’t logged in. Do not use this setting for anything other than local test Jenkins masters.
- Legacy mode
-
Behaves exactly the same as Jenkins <1.164. Namely, if a user has the "admin" role, they will be granted full control over the system, and otherwise (including anonymous users) will only have the read access. Do not use this setting for anything other than local test Jenkins masters.
- Logged in users can do anything
-
In this mode, every logged-in user gets full control of Jenkins. Depending on an advanced option, anonymous users get read access to Jenkins, or no access at all. This mode is useful to force users to log in before taking actions, so that there is an audit trail of users' actions.
- Matrix-based security
-
This authorization scheme allows for granular control over which users and groups are able to perform which actions in the Jenkins environment (see the screenshot below).
- Project-based Matrix Authorization Strategy
-
This authorization scheme is an extension to Matrix-based security which allows additional access control lists (ACLs) to be defined for each project separately in the Project configuration screen. This allows granting specific users or groups access only to specified projects, instead of all projects in the Jenkins environment. The ACLs defined with Project-based Matrix Authorization are additive such that access grants defined in the Configure Global Security screen will be combined with project-specific ACLs.
|
Matrix-based security and Project-based Matrix Authorization Strategy are provided by the Matrix Authorization Strategy Plugin and may not be installed on your Jenkins. |
For most Jenkins environments, Matrix-based security provides the most security and flexibility so it is recommended as a starting point for "production" environments.
Figure 1. Matrix-based security
The table shown above can get quite wide as each column represents a permission provided by Jenkins core or a plugin. Hovering the mouse over a permission will display more information about the permission.
Each row in the table represents a user or group (also known as a "role"). This includes special entries named "anonymous" and "authenticated." The "anonymous" entry represents permissions granted to all unauthenticated users accessing the Jenkins environment. Whereas "authenticated' can be used to grant permissions to all authenticated users accessing the environment.
The permissions granted in the matrix are additive. For example, if a user "kohsuke" is in the groups "developers" and "administrators", then the permissions granted to "kohsuke" will be a union of all those permissions granted to "kohsuke", "developers", "administrators", "authenticated", and "anonymous."
Markup Formatter
Jenkins allows user-input in a number of different configuration fields and text areas which can lead to users inadvertently, or maliciously, inserting unsafe HTML and/or JavaScript.
By default the Markup Formatter configuration is set to Plain Text which
will escape unsafe characters such as < and & to their respective character
entities.
Using the Safe HTML Markup Formatter allows for users and administrators to inject useful and information HTML snippets into Project Descriptions and elsewhere.
Cross Site Request Forgery
A cross site request forgery (or CSRF/XSRF) [1] is an exploit that enables an unauthorized third party to perform requests against a web application by impersonating another, authenticated, user. In the context of a Jenkins environment, a CSRF attack could allow an malicious actor to delete projects, alter builds, or modify Jenkins' system configuration. To guard against this class of vulnerabilities, CSRF protection has been enabled by default with all Jenkins versions since 2.0.
When the option is enabled, Jenkins will check for a CSRF token, or "crumb", on any request that may change data in the Jenkins environment. This includes any form submission and calls to the remote API, including those using "Basic" authentication.
It is strongly recommended that this option be left enabled, including on instances operating on private, fully trusted networks.
Caveats
CSRF protection may result in challenges for more advanced usages of Jenkins, such as:
-
Some Jenkins features, like the remote API, are more difficult to use when this option is enabled. Consult the Remote API documentation for more information.
-
Accessing Jenkins through a poorly-configured reverse proxy may result in the CSRF HTTP header being stripped from requests, resulting in protected actions failing.
-
Out-dated plugins, not tested with CSRF protection enabled, may not properly function.
More information about CSRF exploits can be found on the OWASP website.
Agent/Master Access Control
Conceptually, the Jenkins master and agents can be thought of as a cohesive system which happens to execute across multiple discrete processes and machines. This allows an agent to ask the master process for information available to it, for example, the contents of files, etc.
For larger or mature Jenkins environments where a Jenkins administrator might enable agents provided by other teams or organizations, a flat agent/master trust model is insufficient.
The Agent/Master Access Control system was introduced [2] to allow Jenkins administrators to add more granular access control definitions between the Jenkins master and the connected agents.
As of Jenkins 2.0, this subsystem has been turned on by default.
Customizing Access
For advanced users who may wish to allow certain access patterns from the agents to the Jenkins master, Jenkins allows administrators to create specific exemptions from the built-in access control rules.
By following the link highlighted above, an administrator may edit Commands and File Access Agent/Master access control rules.
Commands
"Commands" in Jenkins and its plugins are identified by their fully-qualified class names. The majority of these commands are intended to be executed on agents by a request of a master, but some of them are intended to be executed on a master by a request of an agent.
Plugins not yet updated for this subsystem may not classify which category each command falls into, such that when an agent requests that the master execute a command which is not explicitly allowed, Jenkins will err on the side of caution and refuse to execute the command.
In such cases, Jenkins administrators may "whitelist" [3] certain commands as acceptable for execution on the master.
Advanced
Administrators may also whitelist classes by creating files with the .conf
extension in the directory JENKINS_HOME/secrets/whitelisted-callables.d/.
The contents of these .conf files should list command names on separate
lines.
The contents of all the .conf files in the directory will be read by Jenkins
and combined to create a default.conf file in the directory which lists all
known safe command. The default.conf file will be re-written each time
Jenkins boots.
Jenkins also manages a file named gui.conf, in the whitelisted-callables.d
directory, where commands added via the web UI are written. In order to disable
the ability of administrators to change whitelisted commands from the web UI,
place an empty gui.conf file in the directory and change its permissions such
that is not writeable by the operating system user Jenkins run as.
File Access Rules
The File Access Rules are used to validate file access requests made from agents to the master. Each File Access Rule is a triplet which must contain each of the following elements:
-
allow/deny: if the following two parameters match the current request being considered, anallowentry would allow the request to be carried out and adenyentry would deny the request to be rejected, regardless of what later rules might say. -
operation: Type of the operation requested. The following 6 values exist. The operations can also be combined by comma-separating the values. The value of
allindicates all the listed operations are allowed or denied.-
read: read file content or list directory entries -
write: write file content -
mkdirs: create a new directory -
create: create a file in an existing directory -
delete: delete a file or directory -
stat: read metadata of a file/directory, such as timestamp, length, file access modes.
-
-
file path: regular expression that specifies file paths that matches this rule. In addition to the base regexp syntax, it supports the following tokens:
-
<JENKINS_HOME>can be used as a prefix to match the master’sJENKINS_HOMEdirectory. -
<BUILDDIR>can be used as a prefix to match the build record directory, such as/var/lib/jenkins/job/foo/builds/2014-10-17_12-34-56. -
<BUILDID>matches the timestamp-formatted build IDs, like2014-10-17_12-34-56.
-
The rules are ordered, and applied in that order. The earliest match wins.
For example, the following rules allow access to all files in JENKINS_HOME
except the secrets folders:
# To avoid hassle of escaping every '\' on Windows, you can use / even on Windows.
deny all <JENKINS_HOME>/secrets/.*
allow all <JENKINS_HOME>/.*Ordering is very important! The following rules are incorrectly written because
the 2nd rule will never match, and allow all agents to access all files and
folders under JENKINS_HOME:
allow all <JENKINS_HOME>/.*
deny all <JENKINS_HOME>/secrets/.*Advanced
Administrators may also add File Access Rules by creating files with the
.conf. extension in the directory JENKINS_HOME/secrets/filepath-filters.d/.
Jenkins itself generates the 30-default.conf file on boot in this directory
which contains defaults considered the best balance between compatibility and
security by the Jenkins project. In order to disable these built-in defaults,
replace 30-default.conf with an empty file which is not writable by the
operating system user Jenkins run as.
On each boot, Jenkins will read all .conf files in the filepath-filters.d
directory in alphabetical order, therefore it is good practice to name files in a
manner which indicates their load order.
Jenkins also manages 50-gui.conf, in the filepath-filters/ directory, where
File Access Rules added via the web UI are written. In order to disable the
ability of administrators to change the File Access Rules from the web UI,
place an empty 50-gui.conf file in the directory and change its permissions
such that is not writeable by the operating system user Jenkins run as.
Disabling
While it is not recommended, if all agents in a Jenkins environment can be considered "trusted" to the same degree that the master is trusted, the Agent/Master Access Control feature may be disabled.
Additionally, all the users in the Jenkins environment should have the same level of access to all configured projects.
An administrator can disable Agent/Master Access Control in the web UI by
un-checking the box on the Configure Global Security page. Alternatively an
administrator may create a file in JENKINS_HOME/secrets named
slave-to-master-security-kill-switch with the contents of true and restart
Jenkins.
|
Most Jenkins environments grow over time requiring their trust models to evolve as the environment grows. Please consider scheduling regular "check-ups" to review whether any disabled security settings should be re-enabled. |
2. Starting with 1.587, and 1.580.1, releases
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.