Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 40 ยท Credentials, Plugins and Security

Security, Users and Authorization

Secure Jenkins with security realms, matrix and role-based authorization, CSRF protection, safe agents, a locked-down script console and regular updates.

A Jenkins controller is a powerful target. It holds credentials, it can run code on many machines, and it can often deploy to production. Anyone who gains control of it gains a great deal else. That is why Jenkins security is not an optional chapter at the end: it is part of how you set the server up on day one.

This lesson explains the two big questions, who are you (authentication, called the security realm) and what may you do (authorization), and then the hardening steps that matter most. Real configuration screens and YAML are read-only; the runnable stand-in is a small permission matrix that decides whether a user may perform an action, so you can see how grants and denials combine.

Two questions

Authentication Who are you? (security realm)
Authorization What may you do? (permissions)

Jenkins asks both on every request.

1 / 2

Security realms: who are you?

A security realm decides how users prove their identity. In Manage Jenkins > Security you pick one:

  • Jenkins' own user database: simple accounts stored in JENKINS_HOME. Fine for a small team or a lab, but passwords are managed by Jenkins itself.
  • LDAP or Active Directory: log in with company credentials. Group membership from the directory can be used for authorization.
  • SSO with SAML or OpenID Connect: through plugins, so users sign in with your identity provider (Okta, Azure AD, Keycloak, Google and so on). This is usually the best choice for companies, because accounts, password policy and multi-factor authentication live in one place and leavers lose access when their identity account is disabled.
  • GitHub and similar OAuth plugins: sign in with a Git hosting account.

Whichever you choose, disable "Allow users to sign up" unless you really want self-registration, and never leave anonymous users with more than the minimum.

Authorization: what may you do?

The authorization strategy decides what each identity may do. The main ones:

  • Anyone can do anything and Logged-in users can do anything: only for experiments. The second is common on first installs and is dangerous because every account is an administrator.
  • Matrix-based security: a grid of users and groups against permissions (Overall/Read, Overall/Administer, Job/Build, Job/Configure, Credentials/View and so on). The Project-based Matrix Authorization variant lets each job or folder add its own grants.
  • Role-based strategy (a plugin): you define roles such as developer or release-manager with a set of permissions, optionally limited to jobs whose names match a pattern, and then assign people or groups to roles. This scales better than editing a matrix per user.

A good starting design is:

Group What they may do
Everyone signed in Read the dashboard (Overall/Read)
Developers Read, build and cancel builds on their team's folder
Release managers The above plus approve deployments and view logs
Admins Overall/Administer (keep this list tiny)

Use folders to separate teams. Permissions granted on a folder apply to the jobs inside it, and folder-scoped credentials follow the same boundary.

How a decision is made

The evaluator below models a matrix. Each rule gives a user or group a set of permissions. Your effective permissions are the union of everything granted to you and your groups. A permission that no rule grants is denied. Real Jenkins has a similar rule: nothing is allowed unless something grants it. (Some strategies, such as the Role Strategy plugin, add pattern matching on job names, which the stand-in omits.)

JS Stand-in: a permission matrix evaluator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Alice is an administrator, so she is allowed everything. Bob can build but not approve deployments, Carol (in two groups) gets the union of both, and Dave can look at the dashboard but do nothing else. Real Jenkins treats Overall/Administer in a similar all-powerful way, which is why very few people should have it.

Turn on the protections that are not optional

  • CSRF protection (Cross-Site Request Forgery): enabled by default in current versions. Jenkins requires a crumb with state-changing requests so that a malicious web page cannot make your logged-in browser start builds. Scripts that call the API need a crumb too, or an API token, which is the better approach.
  • API tokens: each user can create tokens under their profile. Use a token for scripts and webhooks instead of a password, and revoke it when it is no longer needed.
  • Agent-to-controller access control: agents are less trusted than the controller. Jenkins blocks agent processes from reading arbitrary controller files or calling sensitive controller APIs. Do not disable this protection to make a plugin work.
  • Set the number of executors on the built-in node to 0. Builds should run on agents, never on the controller, because a build running on the controller can read JENKINS_HOME, including secrets. Agents, Labels and Scaling shows how to provide agents.
  • Use HTTPS at the proxy, and set the Jenkins URL correctly (Installing Jenkins).
  • Pipeline sandbox: Groovy in Pipelines runs in a sandbox by default. Scripts that need blocked methods require an administrator's script approval. Approve nothing you do not understand; approvals are standing exceptions.

The script console is a root shell

Manage Jenkins > Script Console runs arbitrary Groovy inside the controller, with the full rights of the Jenkins process. It is useful for administration and also exactly what an attacker wants. Only administrators should reach it, and in a hardened setup you may disable it entirely or keep access to a very small group. If someone with Overall/Administer is compromised, assume everything the controller stores is exposed.

Audit, review and update

  • Audit trail: record who changed configuration. Plugins can log configuration changes and logins; keep these logs outside Jenkins so an attacker cannot erase them.
  • Review access regularly: remove leavers, shrink the admin group, and look for accounts and API tokens that have not been used.
  • Update promptly. The Jenkins project publishes security advisories with CVE numbers for core and plugins, often with an LTS patch release. Many incidents involve a known issue that was fixed months earlier. Subscribe to the announcements, and plan to patch within days for serious ones (Plugins covers the update workflow).
  • Protect your configuration: with Configuration as Code, security settings live in Git and drift is visible in review.
  • Limit who can change Jenkinsfiles. A pipeline author can run code on agents and use any credential in scope, so repository permissions are part of Jenkins security.

Never expose an unconfigured Jenkins to the internet. A fresh install with "Logged-in users can do anything", self-registration enabled and the built-in node running builds is a common way servers get taken over.

A configuration-as-code taste

Settings like the ones above can be written as YAML for the Configuration as Code plugin. This is a read-only illustration of the shape, not a copy-and-paste recipe:

YAML
jenkins:
  numExecutors: 0
  securityRealm:
    local:
      allowsSignup: false
  authorizationStrategy:
    globalMatrix:
      entries:
        - group:
            name: "authenticated"
            permissions:
              - "Overall/Read"
        - user:
            name: "admin"
            permissions:
              - "Overall/Administer"

Check the plugin's documentation for the exact schema of your version. The lesson on Jenkins Configuration as Code goes deeper.

What is real and what is the stand-in

Security realms, matrix and role-based strategies, CSRF crumbs and the script console are real Jenkins features, and the settings described are the ones to look for. The TryIt is a stand-in: real Jenkins has many more permission types, can explicitly combine inheritance from folders, and the Role Strategy plugin works with name patterns, none of which the small evaluator reproduces.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between a security realm and an authorization strategy?

    Authentication (realm) identifies a user, authorization (strategy) maps identities to permissions.
  2. 2. Why should the built-in node have 0 executors?

    Code running on the controller shares its file system and process rights. Running builds on agents keeps untrusted build code away from secrets.
  3. 3. Carol belongs to the developers and release-managers groups. What are her permissions?

    Permissions are additive in a matrix: you get everything granted to you directly or through your groups.
  4. 4. Which statement about the script console is right?

    Anything you can do in Groovy there, the Jenkins process can do, including reading credentials.

Summary

  • Authentication uses a security realm (local, LDAP, SSO/OIDC); authorization uses a strategy such as matrix or role-based security.
  • Grant the least access that works; keep Overall/Administer for a handful of people.
  • Keep CSRF protection on, use API tokens for scripts, and never run builds on the controller.
  • Treat the script console and Pipeline script approvals as high-risk powers.
  • Audit access, put settings in code, and apply core and plugin security updates quickly.

Next, scale out beyond one machine in Agents, Labels and Scaling.