SSO, LDAP, OIDC/SAML Plugins, External Identity, RBAC Patterns, and Enterprise Access Governance: Concepts, Architecture, and Mental Model

1. The practical problem: successful login is not a permission model

As Jenkins moves from a small team to an enterprise service, local user management becomes difficult to audit and deprovision. LDAP, OIDC and SAML solve the identity side of that problem by letting Jenkins rely on a directory or identity provider. They do not automatically produce a safe Jenkins authorization design.

A common failure pattern is: “the IdP says the user belongs to engineering, therefore give that group Overall/Administer.” That collapses authentication, group naming, and Jenkins privilege into one broad mapping. The safer model treats each boundary independently and records evidence at each transition.

2. Mental model: identity enters; Jenkins still decides

The flow below is causal. The external system authenticates and returns an identity plus attributes/claims. The Jenkins security realm converts that external assertion into a Jenkins principal and groups. An authorization strategy then evaluates those names against Jenkins permissions. Only after that can a browser session or API token perform an item or administrative action.

flowchart TD
A[External IdP or directory] --> B[Authentication plugin / Security Realm]
B --> C[User identity + group claims]
C --> D[Jenkins authorization strategy]
D --> E[Global / folder / item permissions]
E --> F[Browser session or Jenkins API token]
F --> G[Audited admin or job action]
A --> H[Disable user / remove group]
H --> I[Session-token reevaluation and deprovision verification]
J[Offline recovery procedure] --> B

Arrow-by-arrow: the realm proves identity; group names are inputs, not permissions; the authorization strategy assigns Jenkins privileges; sessions/tokens carry an already-authenticated identity into later requests; and deprovisioning is complete only after access tests prove that old sessions/tokens and group mappings no longer grant the capability.

3. State map before changing anything

4. Read-only inspection first

Before switching realms or changing group mappings, capture the controller identity and current access model. On a disposable lab controller, record Jenkins/Java and plugin versions, current security realm, authorization strategy, built-in node executor count, and existing user/group mappings. In a real organization, also record the IdP application/client ID, issuer/metadata endpoint, redirect/callback URL, group-claim name, and documented owners.

Controller: jenkins-lab-30
Jenkins: 2.568.3 LTS
Java: 21
Realm: current value (record before change)
Authorization: current value (record before change)
Built-in executors: 0
Identity plugins: versioned inventory
Synthetic principals only: alice, bob, carol, recovery-owner
Protected folder used by lab: identity-lab/protected

5. Authentication versus authorization

A successful SSO redirect is therefore only one test. A complete acceptance test includes both positive and negative permission checks.

6. Break-glass is a recovery design, not “another permanent admin login”

Jenkins normally operates with one configured security realm. Do not assume a Jenkins-local account remains usable after switching the realm to LDAP/OIDC/SAML. The chapter’s recovery pattern is instead: keep an offline, access-controlled recovery configuration and documented procedure that can restore a known local realm and recovery administrator from trusted controller/JCasC access if the external IdP is unavailable or misconfigured. Test the procedure in a disposable controller, then return to the external realm.

The break-glass procedure should require explicit incident authorization, produce an audit record, rotate/revoke temporary recovery credentials afterward, and never enable anonymous access.

7. Sessions, API tokens and deprovisioning are separate lifecycles

Disabling a user in an IdP may prevent the next interactive login, but it does not automatically prove that every existing Jenkins browser session or Jenkins-side API token has stopped working. Exact behavior depends on the realm/plugin and provider. LDAP, for example, has plugin-specific account-state handling for alternative authentication mechanisms; OIDC/SAML sessions depend on provider and plugin session/logout behavior.

Therefore a deprovision runbook verifies: interactive login fails, group membership is no longer honored after a fresh session, existing sessions are invalidated according to policy, and Jenkins-side API tokens are revoked or demonstrably denied. Record the evidence.

8. DevOps connection: identity is part of the delivery control plane

A reproducible delivery path needs more than a source SHA and artifact digest. It also needs evidence of who could approve, configure, trigger, read credentials, use privileged agents, or administer Jenkins at that time. External identity simplifies lifecycle management only when the group-to-permission contract is explicit and reviewed.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog — chapter baseline: Jenkins 2.568.3 LTS; labs use Java 21.
• Securing Jenkins — security realm versus authorization strategy, least privilege, controller isolation and access-control fundamentals.
• LDAP plugin — version 825.v2fca_37dd5b_cb_ (requires Jenkins 2.504.3); current release includes fixes beyond earlier LDAP referral/SSRF advisories.
• OpenID Connect Authentication plugin — version 4.718.ve731df6ca_88a_ (requires Jenkins 2.539); issuer/audience/group-claim behavior is provider configuration, not Jenkins authorization by itself.
• SAML plugin — version 4.623.v7875d61cd9f5 (requires Jenkins 2.504.3).
• Matrix Authorization Strategy — version 3.3 (requires Jenkins 2.528.3); supports granular global/project authorization.
• Role-based Authorization Strategy — version 898.vc050ed2424ca_ (requires Jenkins 2.559); supports global/item/agent roles and group assignments.
• Mock Security Realm — version 134.v31b_1cc496b_43; intentionally insecure and suitable only for disposable testing/demonstration.