Users, Authentication Realms, Authorization Strategies, Matrix Permissions, Folders, and Least Privilege: Concepts, Architecture, and Mental Model

1. The problem: “can log in” is not an access-control design

Jenkins answers two different questions for every protected action. First: who is this request? Second: is that identity allowed to perform this action on this object? Authentication answers the first. Authorization answers the second. Mixing them produces unsafe conclusions such as “developers are authenticated, so they can build” or “the job is hidden, so its credentials are safe.”

A controller also has hierarchy. A permission may be global, inherited from a folder, granted on one job, or tied to a different resource type such as credentials. The operational question is therefore not “what role does Alice have?” but “which principal, through which groups, under which authorization strategy, has which permission on which object?”

2. The causal access-control model

A security realm authenticates the request and may provide group memberships. Jenkins then asks the configured authorization strategy whether that principal has the required permission on the target object.

flowchart TD
 A[Request: user or API client] --> B[Security realm]
 B --> C[Authenticated principal + groups]
 C --> D[Authorization strategy]
 D --> E[Global / folder / item / credential scope]
 E --> F[Permission check]
 F -->|allowed| G[Action executes]
 F -->|denied| H[403 / hidden action / denial evidence]
 G --> I[Audit, job, build, or configuration evidence]

A principal can authenticate successfully and still receive an authorization denial. A user can have Overall/Read and Job/Read yet still lack Job/Build. An administrator with Overall/Administer, by contrast, has extremely broad controller authority.

3. Core nouns before configuration

4. Permission families and blast radius

Overall/Read is a prerequisite for most meaningful Jenkins access. Overall/Administer is the highest-power permission and exposes sensitive administration including plugin management and Script Console. It is not a routine developer role.

Job permissions answer different questions. Job/Read permits seeing an item. Job/Build permits scheduling it. Job/Configure permits changing item configuration and is much more powerful because it can change what code executes, where, and with which integrations.

When the Credentials Plugin is installed, Credentials/Create, Credentials/Update, Credentials/Delete, Credentials/View, and Credentials/ManageDomains are separate management permissions. Folder visibility is not evidence that a user should manage a credential store.

5. Matrix Authorization and folder inheritance

Matrix Authorization Strategy provides a global matrix and project-based matrix authorization. In project-based mode, global and parent-folder permissions are inherited by default. The plugin also offers modes to inherit only global configuration or to stop ordinary parent inheritance. Overall/Administer remains special: child ACLs cannot exclude Jenkins administrators.

The plugin also warns that users allowed to configure project-based items can grant themselves other permissions on those items. Treat Job/Configure as a trust boundary, not a cosmetic editor permission.

6. Inspect before changing security

Before changing a realm or matrix, capture the Jenkins/Java/plugin baseline, current security realm, current authorization strategy, a tested administrative recovery identity, and the full item paths you intend to scope. Keep secrets out of the evidence.

docker exec jenkins-ch04 java -version
curl -fsSI http://127.0.0.1:8080/login | grep -i '^X-Jenkins:'
# Then inspect Manage Jenkins → Security as the disposable administrator.

The HTTP header helps prove controller identity; it does not prove access-control configuration. Inspect the realm and strategy in Jenkins itself without copying password hashes, API tokens, credential values, or controller secret keys.

7. Access control does not replace execution isolation

Users with Job/Configure can influence build code. Jenkins therefore recommends not running routine builds on the built-in node. A strong permission matrix combined with controller execution would still leave build code inside the controller filesystem trust boundary.

8. Misconceptions to remove now

• “Authenticated means trusted.” Authentication establishes identity, not permission level.
• “Hidden UI means secure.” Server-side authorization is the boundary.
• “Folder visibility equals credential access.” These are separate permission/scope systems.
• “Removing Administer makes Configure harmless.” Configure can change executable behavior.
• “Project matrices subtract parent grants.” They are commonly inherited/additive unless configured otherwise.

9. Summary

A defensible Jenkins permission model starts with a known identity source, then applies explicit permissions at explicit scopes. Administration stays rare, Configure is treated as code-execution authority, credentials are governed separately, and every important policy claim is proven with both allowed and denied behavior.

Knowledge check

Official references and version notes

• Jenkins Access Control — authentication via a security realm and authorization via an authorization strategy are separate decisions.
• Jenkins Permissions — current definitions for Overall, Job, Run, View, Credentials, and Pipeline-related permissions.
• Managing Security — realms, authorization modes, matrix security, and controller-wide security settings.
• Matrix Authorization Strategy Plugin — global/project matrices, inheritance modes, and item-configuration caveats.
• Folders Plugin — folder-based item organization used by the scoped-access examples.
• Jenkins Credentials security guidance — credential scope and access minimization.
• Controller Isolation — why users who influence build code must not run routine builds on the built-in node.