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.
Beginning with Jenkins 2.214 and Jenkins LTS 2.222.1, the "Enable Security" checkbox has been removed. Jenkins own user database is used as the default security realm.
In versions before Jenkins 2.214 and Jenkins LTS 2.222.1, when the Enable Security checkbox is checked, 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. The "Enable Security" checkbox should always be enabled for any non-local (test) Jenkins environment.
The "Configure Global 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.
Jenkins can use a TCP port to communicate with inbound (formerly known as “JNLP”) agents, such as Windows-based agents. As of Jenkins 2.0, by default this port is disabled.
For administrators wishing to use inbound TCP agents, the two port options are:
Random: The TCP port is chosen at random to avoid collisions on the Jenkins master. The downside to randomized ports is that they are chosen during the boot of the Jenkins controller, making it difficult to manage firewall rules allowing TCP traffic.
Fixed: The port is chosen by the Jenkins administrator and is consistent across reboots of the Jenkins controller. This makes it easier to manage firewall rules allowing TCP-based agents to connect to the controller.
As of Jenkins 2.217, inbound agents may instead be configured to use WebSocket transport to connect to Jenkins. In this case no extra TCP port need be enabled and no special security configuration is needed.
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.
By default Jenkins includes support for a few different Security Realms:
For delegating authentication a servlet container running the Jenkins controller, such as Jetty. If using this option, please consult the servlet container’s authentication documentation.
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.
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.
Delegates the authentication to the underlying Unix
OS-level user database on the Jenkins controller. This mode will also allow re-use
of Unix groups for authorization. For example, Jenkins can be configured such
that "Everyone in the
developers group has administrator access." To support this feature, Jenkins relies on
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:
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:
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 controllers.
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 controllers.
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.
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).
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.
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."
By default the Markup Formatter configuration is set to Plain Text which
will escape unsafe characters such as
& to their respective character
Using the Safe HTML Markup Formatter allows for users and administrators to inject useful and information HTML snippets into Project Descriptions and elsewhere.
A cross site request forgery (or CSRF/XSRF)  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.
The CSRF settings can be found following this path: Manage Jenkins > Configure Global Security > Section: CSRF Protection.
Inside the CSRF section it is possible enable the option "proxy compatibility" that can be useful in case of HTTP proxies filtering out information that the default crumb issuer uses to calculate the nonce value.
If an HTTP proxy sits between your browser client and your Jenkins server and you receive a 403 response when submitting a form to Jenkins, checking this option may help. Using this option makes the nonce value easier to forge.
Before Jenkins version 2.176.2 it was possible disable CSRF directly by Configure Global Security. Now to avoid secure issues since 2.176.2 that option it was removed.
Enable/Unable checkbox before 2.176.2
Enable/Unable checkbox was removed after 2.176.2
CSRF tokens (crumbs) are now only valid for the web session they were created in to limit the impact of attackers obtaining them. Scripts that obtain a crumb using the /crumbIssuer/api URL will now fail to perform actions protected from CSRF unless the scripts retain the web session ID in subsequent requests.
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.
Conceptually, the Jenkins controller 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 controller 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/controller trust model is insufficient.
The Agent/Master Access Control system was introduced  to allow Jenkins administrators to add more granular access control definitions between the Jenkins controller and the connected agents.
As of Jenkins 2.0, this subsystem has been turned on by default.
For advanced users who may wish to allow certain access patterns from the agents to the Jenkins controller, 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" 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 controller, but some of them are intended to be executed on a controller 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 controller 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"  certain commands as acceptable for execution on the controller.
Administrators may also whitelist classes by creating files with the
extension in the directory
The contents of these
.conf files should list command names on separate
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 also manages a file named
gui.conf, in the
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.
The File Access Rules are used to validate file access requests made from agents to the controller. Each File Access Rule is a triplet which must contain each of the following elements:
deny: if the following two parameters match the current request
being considered, an
allow entry would allow the request to be carried out
deny entry 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
all indicates 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 controller’s
<BUILDDIR> can be used as a prefix to match the build record directory,
<BUILDID> matches the timestamp-formatted build IDs, like
The rules are ordered, and applied in that order. The earliest match wins.
For example, the following rules allow access to all files in
# 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
allow all <JENKINS_HOME>/.* deny all <JENKINS_HOME>/secrets/.*
Administrators may also add File Access Rules by creating files with the
.conf. extension in the directory
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,
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
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.
While it is not recommended, if all agents in a Jenkins environment can be considered "trusted" to the same degree that the controller 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
slave-to-controller-security-kill-switch with the contents of
true and restart
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.