We start with the simplest picture: two jobs, two settings, and how they differ.

Jenkins is a tool that automates building, testing, and delivering software. It is usually reached through a web page, and also through scripts and other tools. Whoever connects must be identified, and their actions must be limited to what they are permitted to do. Jenkins handles this with two settings that live side by side on the security configuration page.

A security realm is the part of Jenkins that handles authentication, which means proving identity. It decides where user names and passwords come from, and how a person proves they are who they claim to be. It can be Jenkins’ own list of users, or a company directory, or a single sign-on service.

An authorization strategy is the part of Jenkins that handles authorization, which means granting rights. Once Jenkins knows who someone is, the strategy decides which actions they may perform: view a job, start a build, change a setting, or manage the whole server.

flowchart LR
  A["A person or script contacts Jenkins"] --> B["Security realm checks who you are"]
  B --> C["Authorization strategy checks what you may do"]
  C --> D["Allowed so the page or action proceeds"]
  C --> E["Denied so an error page is shown"]
    

Two settings, chosen separately

To see why security matters so much in Jenkins, imagine a Jenkins server with no protection at all.

What an open Jenkins can do

A Jenkins server is not just a dashboard. It stores credentials for cloud accounts, Git servers, and production machines. It can run any command on its agents, and can deploy software to real customers. Anyone who can change a job can make it run any command they like. So, an unprotected Jenkins is much like handing strangers a set of keys to the company’s servers along with an instruction manual.

How the defaults changed

Jenkins began in 2011 as a fork of an older project called Hudson, in an era when build servers often sat on a private network and were trusted by everyone who could reach them. Over the years, build servers became a prime target for attackers, because of the secrets and power they hold. With Jenkins 2.0, released in 2016, the setup process began to enable security by default. A new installation asks you to unlock it with an initial password, and then to create a first administrator account.

The problem these settings solve

• Unknown visitors. Without authentication, nobody knows who changed a job or started a deployment.
• Too much power. Without authorization, every user can do everything, including things they should never touch.
• Team boundaries. Without fine-grained rules, one team can read or change another team’s jobs and secrets.
• Accountability. Without named accounts, auditors cannot say who did what, and when.
• Departures. When someone leaves the company, their access must end in one place, not twenty.

A handful of terms come up in every discussion of Jenkins security. Learn them once here.

A few more Jenkins words

The controller is the main Jenkins server, and it is the place where security is enforced. An agent is a worker machine that runs builds. A job is a saved description of work, and a folder is a container for jobs. An administrator is a user with the highest permission, often called Administer, who can change any setting. A session is the period after login during which Jenkins remembers you, usually through a small cookie in your browser.

These two words are often confused. Getting them straight is the foundation for everything else.

The order matters

Authorization can only work after authentication. Jenkins must know who you are, and which groups you belong to, before it can decide what you may do. If the security realm is wrong, for example if it cannot tell which groups you are in, the strategy has nothing to work with, and you may be denied even though the permission rules are correct.

What happens on each request

Jenkins can take its identity information from several places. Here are the usual choices.

Choosing a realm

• One person or a lab. Jenkins’ own database is simplest, with sign-up turned off.
• A team with a company directory. Use the directory, so that people use their normal passwords and leave the system when they leave the company.
• A company with central single sign-on. Use it, so that multi-factor checks, password rules, and account removal apply to Jenkins too.
• Anything that needs groups. Choose a realm that supplies groups, since group-based rules are far easier to maintain than lists of individual names.

This is the simplest realm, and the one that every new installation meets first. It is worth understanding well, including its limits.

What it is

With this realm, Jenkins keeps its own list of users, each with a login name, a password, and some profile details. The passwords are stored in a hashed form, which means Jenkins keeps a scrambled version that cannot be turned back into the original password. The user records live in Jenkins’ data folder on the controller.

How a new installation starts

The sign-up switch

This realm has an option to allow users to sign up. When it is on, anyone who can reach the login page can create an account for themselves. That may be fine on a private lab, but it is dangerous in combination with a loose authorization strategy. If the strategy says that any logged-in user can do anything, then anyone who signs up instantly becomes a full administrator. Sign-up should almost always be turned off on any Jenkins that holds real secrets.

Most companies do not want a separate password list for every tool. External realms let Jenkins borrow identities from a central system.

Directory realms

A directory is a central database of people and groups that many company systems share. Two common examples are LDAP directories and Microsoft’s directory service. When Jenkins uses a directory realm, it does not store passwords itself. When a person logs in, Jenkins asks the directory server to check the password, and asks it which groups the person belongs to. To make this work, an administrator gives Jenkins the address of the directory, an account it may use to search, and rules for finding users and groups.

Single sign-on realms

With single sign-on, Jenkins does not see the password at all. It hands the person over to a separate identity provider, which does the login, possibly including a second check such as a code from a phone. The provider then sends Jenkins a signed message that says who the person is and, often, which groups they belong to. Two common protocols for this are called SAML and OpenID Connect.

sequenceDiagram
  participant U as User Browser
  participant J as Jenkins
  participant I as Identity Provider
  U->>J: Open a Jenkins page
  J-->>U: Redirect to the identity provider
  U->>I: Sign in with the company account
  I-->>U: Signed proof of identity and groups
  U->>J: Present the signed proof
  J->>J: Create a session and map groups to permissions
  J-->>U: Show the page
    

Why organisations prefer them

Things to plan for

• Group names must match. Jenkins rules refer to groups by name, and the name the provider sends must be spelled exactly the same way.
• Provider outages. If the identity provider or directory is down, people cannot log in. Plan how administrators will regain access, and keep tested recovery steps.
• Session lifetimes. Decide how long a login lasts, balancing safety against annoyance.
• Scripts still need identities. Non-browser tools cannot use a browser login. They use tokens, described in Chapter 13.
• Test with a second browser. Before you save a change to the realm, keep your current administrator session open, and test the new login in a private window, so you cannot lock yourself out.

Once Jenkins knows who someone is, the strategy decides what they may do. Here is the whole menu, from loosest to most detailed.

The first three are rarely enough

The first three strategies treat everyone alike. They may be fine for a personal server, but as soon as you have two teams, one of which should not touch the other’s jobs or secrets, they fail. Real access control begins with the matrix and role strategies, which let you say different things about different people.

The permission matrix is the classic Jenkins answer to “who may do what”. It is a grid you can read at a glance.

The grid

In matrix-based security, down the side are users and groups, and across the top are permissions. You tick a box where a person or group should have a permission. A person’s rights are everything ticked for them, plus everything ticked for every group they belong to, plus everything ticked for the special “authenticated” and “anonymous” identities that apply to them.

Rights add up, never subtract

A key feature of the matrix is that permissions only add. If a group has a permission, and you are a member of that group, you have it. There is no way to say “everyone in the developers group except Sam”. If Sam is in the group, Sam has the rights of the group. To treat Sam differently, you must remove Sam from the group, or create a different group. Keep this in mind when designing groups.

Project-based matrix: rules per job

The project-based variant keeps the global grid, and adds a second grid to each job and folder. This lets a team have extra permissions on its own jobs only. For example, the payments team can be given “configure” rights on the payments folder, but nothing on the search folder. Jobs and folders can also inherit rules from the folder above, which reduces repetition.

When the grid gets too big, roles keep it tidy. A role is a named bundle of permissions that you can hand out like a job title.

The role-based strategy, provided by the Role Strategy plugin, introduces three kinds of roles.

flowchart TD
  A["Users and groups from the security realm"] --> B["Global roles such as admin and viewer"]
  A --> C["Item roles matched to folders or job name patterns"]
  A --> D["Agent roles matched to agent names"]
  B --> E["Permission check on every request"]
  C --> E
  D --> E
    

Why roles scale better

• Meaningful names. “team-payments-developer” tells a reader what the role is for, while a row of ticks does not.
• Patterns for jobs. One pattern covers all present and future jobs of a team, without editing each one.
• One place to audit. All rules are on one management screen, not scattered across job pages.
• Reuse. The same role can be assigned to many groups.

Things to watch

• Pattern mistakes. A pattern that is too broad gives a team access to jobs that are not theirs, and one that is too narrow leaves their new jobs invisible.
• Naming discipline. Patterns rely on jobs being named consistently, or on being placed in folders. Folders are usually the more reliable boundary.
• Plugin dependence. The strategy is a plugin, so keep it updated and read its release notes.
• Additive rights. As in the matrix, rights add up and never subtract.

Permissions are the atoms of authorization. Here are the ones you will meet most often, grouped by what they protect.

Permissions that are more dangerous than they look

• Job Configure. Anyone who can change a job can make it run any command on the build agents, and can often reach the credentials that the job uses. It is nearly as powerful as it sounds.
• Job Workspace. Workspaces can contain secrets that builds wrote to disk.
• Credentials Use. The right to use a credential in a job is more powerful than the right to view its entry.
• Overall Administer. This includes the ability to run scripts on the controller, which amounts to full control of the machine.

Two special identities appear in every Jenkins rule set. Understanding them prevents some of the most common mistakes.

Anonymous read access

Some strategies offer a tick box for allowing anonymous users to read. It lets people see the dashboard and job results without logging in. That may suit a public open source project. For an internal Jenkins, it exposes build logs, job names, and settings to anyone on the network, and logs sometimes contain sensitive information. The safe default for an internal server is no anonymous access at all.

Authenticated as a building block

Because “authenticated” includes everyone with a login, it is handy for granting basic rights, such as Overall Read, to all employees. But be careful. If the realm is an open directory, or allows sign-up, “authenticated” may include far more people than you intend. Anything you grant to “authenticated” is granted to every account the realm accepts.

People are not the only ones who talk to Jenkins. Scripts and other tools do too. They need identities as well.

API tokens

An API token is a long random secret that a user can generate in their own profile. A script sends it, together with the user’s name, instead of a password. Tokens have several advantages over passwords for automation. They can be created and revoked individually, so one leaked token does not force a password change. Several tokens can exist for one user, one per script. And they work with any security realm, including single sign-on, where scripts cannot log in through a browser.

The rights of a token

A token acts with the same rights as the user who created it. It does not have a smaller set of powers. So a token created by an administrator is an administrator’s token. For automation, create a dedicated account for the script, give that account only the permissions it needs, and create the token under that account.

Cross-site request forgery protection

A web attack called cross-site request forgery tricks your browser, while you are logged in to Jenkins, into sending a hidden request to Jenkins from another website. To stop this, Jenkins can require a special one-time value, called a crumb, with each change made through the web interface. This protection is on by default in current Jenkins versions and should stay on. Scripts that call Jenkins over the web sometimes need to fetch a crumb first, or use an API token, which is exempt in the usual setups.

This chapter lifts the lid. Seeing the machinery makes many strange behaviours easy to understand.

The authentication object

For every request, Jenkins builds a small record of who is asking. It holds the user’s name, and the list of groups and special identities that apply to them: the groups from the realm, plus “authenticated” for logged-in users, or “anonymous” for others. This record travels with the request wherever it goes inside Jenkins. Even code that runs on behalf of a person, such as a build they started, is associated with an identity, either theirs or the system’s.

The permission check

Whenever Jenkins is about to do something that requires a right, for example showing a job page, it asks the access control list of that item: does this identity have this permission? The list belongs to the authorization strategy. In a global matrix, one list covers everything. In a project-based matrix, each job or folder may have its own list, and Jenkins combines it with the parent’s and the global one. In a role-based strategy, the plugin works out which roles apply to the item and the person, and answers from them. If the answer is no, Jenkins refuses.

Where the pieces are stored

Sessions and caching

After login, Jenkins remembers a person with a session cookie. Group memberships from an external realm are often cached for a while, to avoid asking the directory on every click. This means that a change made in the directory, such as adding someone to a group, may take a little time to show up in Jenkins, and a person may need to log out and in again to see it at once.

The administrator permission is the most powerful in Jenkins. Handling it well is the heart of a safe setup.

What administrator really means

Administrator, or Overall Administer, sounds like “can change settings”. In reality it means much more. An administrator can install plugins, change the security settings, read and change every job, and use the script console, a page that runs any program code on the controller. That code can read every stored credential in a decrypted form, read files on the server, and run commands as the account that Jenkins runs under. So, an administrator on Jenkins is very close to being a full administrator of the server itself.

Practical rules

Splitting the powers

Some setups separate powers further. Newer Jenkins versions add narrower permissions, for example one that lets a person read system configuration without changing it, which suits auditors and support staff. There is also an experimental permission for managing certain settings without full administrator rights. These options can reduce how many people hold the full permission, but they should be tested and understood before use, since the details depend on your version.

Running builds under specific identities

Builds also run as someone. By default, they run with the authority of the system, which may exceed that of the person who started them. Plugins exist that let a job run as a chosen user, so that the build has only that user’s rights. Used well, this limits what a compromised job can do. Used carelessly, it adds confusing layers, so keep it simple, and test it.

Good login and permission settings are necessary, but not sufficient. These surrounding habits keep the whole setup strong.

Reaching Jenkins safely

Most companies place Jenkins behind a reverse proxy or a gateway that handles encrypted connections, and often adds extra login checks or network limits. Others keep Jenkins reachable only from the company network or through a VPN. If Jenkins must be reachable from the internet, for example to receive webhooks from a code-hosting service, expose only the narrow paths that need it, and keep the login page out of public reach.

The lock-out problem

It is easy to change security settings in a way that stops everyone from logging in, including the administrator. A documented recovery path exists, which involves someone with access to the server temporarily switching security off in the configuration file and restarting. This is a last resort, requires access to the machine, and must be reversed at once. Because it can reset protections, restrict access to the server and to Jenkins’ data folder to the smallest possible group. It is much better to avoid the problem by testing changes carefully and keeping an administrator session open while you do.

When a person cannot get in, or when you need to know who did what, here is where to look.

What Jenkins and its plugins can show you

• The system log. Shows login failures, realm connection problems, and security warnings.
• Audit plugins. Record who changed jobs, settings, and security rules, and when.
• The users page. Lists known users and their last activity.
• The permission and role screens. Show who holds which rights.
• The web server or proxy logs. Show every request, including from tools and scripts, with addresses and outcomes.
• The identity provider or directory logs. Show login attempts on the central side.

flowchart TD
  A["A user cannot log in or is denied"] --> B{"Can the user log in at all"}
  B -->|No| C{"Is the security realm reachable such as the directory or identity provider"}
  C -->|No| D["Fix the connection, certificates, or outage"]
  C -->|Yes| E["Check the user name format, password, account status, and realm settings"]
  B -->|Yes| F{"Is there an access denied message"}
  F -->|Yes| G["Check the groups the user belongs to and the permissions granted to them"]
  F -->|No| H["Check overall read, item level rules, folder inheritance, and cached group data"]
    

Common symptoms and causes

Signals worth reviewing regularly

Once a quarter, review the list of administrators, the members of powerful groups and roles, the service accounts and their tokens, and the users who have not logged in for months. Check that anonymous access is what you intend. Compare the current security settings with the version in your records. Small drift, such as a temporary permission that was never removed, is the usual way a tidy setup decays.

Patterns are choices that keep a Jenkins safe and easy to run. Anti-patterns are habits that slowly turn it into an open door.

A simple way to choose

flowchart TD
  A["Choosing an authorization strategy"] --> B{"Is it a personal or lab Jenkins with one trusted user"}
  B -->|Yes| C["Logged in users can do anything with no anonymous access and sign up off"]
  B -->|No| D{"Do teams need separate access to their own jobs"}
  D -->|No| E["Matrix based security with groups"]
  D -->|Yes| F{"Do you need pattern based rules across many teams"}
  F -->|Yes| G["Role based strategy with folders per team"]
  F -->|No| H["Project based matrix with folders"]
    

Patterns that help

Anti-patterns to avoid

A balanced view of the Jenkins security model, and the habits that keep it working for you.

Best practices in one place

1. Turn security on, and keep it on. Never run a real Jenkins with anyone able to do anything.
2. Use a central realm. A directory or single sign-on, with multi-factor checks for administrators.
3. Turn off sign-up on the built-in database, or avoid that realm for shared servers.
4. Deny anonymous access unless the server is deliberately public.
5. Grant rights to groups, and manage membership in the directory.
6. Keep administrators to a few people, with separate accounts for administrative work.
7. Use folders and roles or project matrices to give each team its own space.
8. Use service accounts and named tokens for scripts, and rotate them.
9. Serve Jenkins over HTTPS, limit who can reach it, and keep it and its plugins updated.
10. Run no builds on the controller.
11. Keep security settings as code, review changes, and record who made them.
12. Review access quarterly, and test as an ordinary user.

The mistakes seen most often

Let us follow one imaginary company as it tightens a Jenkins that grew without much planning.

The starting point

A company has one Jenkins server shared by four teams: Payments, Search, Mobile, and Platform. It was set up three years ago by one engineer. It uses Jenkins’ own user database with sign-up allowed, and the strategy “logged-in users can do anything”, with anonymous read access switched on so that managers can look at the dashboard. There are about sixty accounts. Nine belong to people who have left the company. Everyone, including an intern and two contractors, is effectively a full administrator. Last month, a contractor’s script accidentally deployed to the wrong environment, and nobody could say who had started it.

Here is how the security realm and authorization tend to be arranged in real Jenkins installations. These are illustrative patterns in general terms, not claims about the private setups of any particular company.

Jenkins is one of the most widely used automation servers, and organisations of every size face the same two questions of identity and permission. What tends to be common is a habit of using central login, giving teams their own folders, keeping administrators few, and reviewing access regularly. The patterns below show that habit in practice.