Access Control

Table of Contents

Security Realm
Authorization
Matrix-based security
Permissions
Common Configuration Mistakes
Disabling Access Control

Jenkins access control is split into two parts, both configured on the Manage Jenkins >> Configure Global Security page.:

Authentication (control who can access the Jenkins instance) is done using a security realm. The security realm determines user identity and group memberships.
Authorization (determine who is allowed to do what on the Jenkins instance) is done by an authorization strategy. This controls whether a user (directly or through group memberships) has a permission.

These can be independent, or work in combination:

An example of an independent configuration is using Active Directory or LDAP as security realm, and something like Matrix Authorization Strategy as the authorization strategy.
An example of a related security realm and authorization strategy configuration is GitHub Authentication. While the Github Authentication security realm can be used with a generic authorization strategy, it also provides an authorization strategy that looks up a user’s repository permissions on GitHub, and grants or denies permissions to related jobs in Jenkins based on that.

Jenkins can be set up to have basic access control happen outside of it. Some examples:

The built-in Winstone/Jetty servlet container wrapper provides options that implement a basic security realm outside Jenkins.
If Jenkins is running behind a reverse proxy like Nginx or Apache, those can limit access to Jenkins.

An advantage of these approaches is that they do not allow any access to Jenkins unless a user is authorized, reducing the impact of security issues in Jenkins or plugins especially when accessible from the internet. A disadvantage is the lack of integration with Jenkins access controls and potentially even interfering with it (such as when trying to authenticate scripted clients).

Using both the Security Realm and Authorization configurations, you can configure very relaxed or very rigid authentication and authorization schemes with different degrees of granularity in Jenkins.

Security Realm

The Security Realm defines the source of authenticated user (or identity) information. By default Jenkins includes support for a few different Security Realms:

Delegate to servlet container: 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.
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. When this is implemented, use the Manage Jenkins >> Manage Users page to define users in the Jenkins user database. By default, users and groups come from the Jenkins internal user database. Smaller, more informal installations can use this internal database, but Enterprise installations usually use a corporate service (LDAP, AD, or UNIX), so that users can log into Jenkins with their usual username and password.
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 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 PAM which may need to be configured external to the Jenkins environment.

Unix allows a user and a group to have the same name. In order to disambiguate, use the @ prefix to force the name to be interpreted as a group. For example, @dev would mean the dev group and not the dev user.

Plugins can provide additional security realms which may be useful for incorporating Jenkins into existing identity systems, such as:

To see a list of all plugins for alternate security realms and other authentication tools:

Go to menu:Manage Jenkins[Manage Plugins].
Select the Available tab.
Enter "Authentication and User Management" into the search box.

This displays a list of relevant plugins. You can right-click the name of any plugin to read more about it.

For demonstrations and testing, consider using the Mock Security Realm. This provides an insecure security realm that is easy to set up.

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 controllers.

This authorization strategy is very rarely a good choice, as it allows even anonymous users to administer Jenkins. As a rule of thumb, it should not be used. Never rely on the Jenkins URL to not be known outside your team or organization alone for security.

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 controllers.
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.

This authorization strategy is the default with Jenkins’s single admin user when setting up Jenkins with the setup wizard. It can be a sensible choice as long as only fully trusted users have accounts to access Jenkins.

However, if you later switch to an authentication realm that allows untrusted users to have an account, those users may get administrative access to Jenkins if you keep this authorization stategy. Examples include enabling account signup for Jenkins' own user database, or various other authorization realms, many of which (GitHub, Google, GitLab, etc.) allow anyone to sign up for an account.

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

For most Jenkins environments, Matrix-based security provides the most security and flexibility so it is recommended as a starting point for "production" environments.

Configure Global Security - Matrix authorization

Figure 1. Matrix-based security

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.

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 displays 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."

Permissions

At a very basic level, the Overall/Read permission provides users some basic access to Jenkins. This permission is a prerequisite for more substantial access to Jenkins. Without this permission, only very few features explicitly intended to be used without authentication are available.

The highest level of permissions is Overall/Administer. With this permission, users can upload and install plugins and have access to the Script Console.

Between these two extremes is finer-grained permission control involving other permissions. Permissions in Jenkins have a scope: They can be granted globally, on an item (like a folder or job), on a build, etc. Whenever a user attempts to do something that is protected by permissions, the authorization strategy is checked for whether the current user has the specific permission (e.g., Job/Read) on the specific object (e.g., a job). Exactly how permissions are assigned and whether and how they’re inherited is controlled by the specific authorization strategy.

As an example, Matrix Authorization Strategy provides two different authorization strategies:

One provides a single global configuration of all permissions. A user granted Item/Read will be granted that permission everywhere.
One provides a project-based configuration. In this model, permissions can be granted globally (as in the previous strategy), or only on specific folders, jobs, or agents. Permissions are by default inherited, but that can be customized as well, so that users granted Item/Read globally or on a parent folder may be excluded from access to a job.

For more details about the various permissions in Jenkins and the level of access they grant, see Permissions.

Common Configuration Mistakes

When configuring authentication and authorization in Jenkins, it is easy to accidentally allow far more access than intended. See the documentation on the access given to administrators about the impact of unintentionally granting Administer permission.

Anonymous and authenticated users: Similar to the previous items, you should generally not grant significant permissions to anonymous (the anonymous user) or authenticated (any authenticated user) when using an authorization strategy that allows finer-grained control (like Matrix Authorization Strategy). Granting Overall/Administer permission to anonymous is similar to Anyone can do anything, while granting that permission to authenticated is essentially the same as Logged-in users can do anything.
Built-in node: Users with limited permissions must not be able to configure jobs that run on the built-in node. When setting up a new Jenkins instance, adding users and switching authorization strategies, it is important to also set up distributed builds and limit what jobs are able to run on the built-in node.