Before learning how to connect Jenkins to a company login, we need to understand what goes wrong when it is not connected.

What Jenkins is, in one paragraph

Jenkins is an automation server. Teams use it to compile code, run tests, package software and push it to servers. Because it holds the power to change production systems, it usually also holds secrets such as cloud credentials, signing keys and deployment tokens. In other words, Jenkins is not just a tool; it is a powerful and sensitive doorway into your company.

The problem with local Jenkins accounts

Out of the box, Jenkins can keep its own list of users and passwords. That works for a small lab, but in a company it creates real trouble. Each person now has one more password to remember, and people tend to reuse passwords or choose weak ones. When an employee leaves, someone must remember to delete the Jenkins account, and that step is easy to forget. Nobody can enforce company rules such as multi-factor authentication or password rotation on a private Jenkins list.

What SSO changes

With SSO, Jenkins stops storing passwords entirely. It asks the company identity system, “Who is this person?”, and trusts the answer. Password rules, multi-factor prompts, account lockouts and employee offboarding all live in one place. When the security team disables a person in the central directory, that person can no longer sign in to Jenkins either, without anyone touching Jenkins.

Three simple ideas sit underneath every SSO project. If these are clear, the rest of the guide becomes easy.

The split that Jenkins makes

Jenkins has a very clean design here. It separates authentication and authorization into two independent settings. One setting, called the security realm, decides how people prove who they are. The other, called the authorization strategy, decides what each known person may do. SAML replaces only the first one. Everything about permissions still lives in Jenkins, and that detail is the source of most planning decisions later in this guide.

SAML stands for Security Assertion Markup Language. It is a mature, XML-based standard, finalized in 2005, that lets one system tell another system who a person is in a way that can be cryptographically trusted.

SAML has its own vocabulary. Learn these words once and every vendor document becomes readable, whether it comes from Okta, Microsoft Entra ID, Keycloak, Ping Identity or Active Directory Federation Services.

Now we put the vocabulary into motion and follow one person from the moment they open Jenkins to the moment they see the dashboard.

The service-provider-initiated flow

This is the flow that matters most for Jenkins, because people normally start by opening a Jenkins link from a bookmark, a chat message or a pull request. Jenkins is the one that notices the visitor is a stranger and starts the conversation.

sequenceDiagram
    participant U as User Browser
    participant J as Jenkins (Service Provider)
    participant I as Identity Provider
    U->>J: 1. Open Jenkins page
    J-->>U: 2. Not signed in, redirect with AuthnRequest
    U->>I: 3. Deliver AuthnRequest
    I->>U: 4. Show login and MFA prompt
    U->>I: 5. Prove identity
    I-->>U: 6. Signed assertion in a form
    U->>J: 7. Post assertion to ACS endpoint
    J->>J: 8. Validate signature, time, audience
    J-->>U: 9. Create session, show dashboard
        

The identity-provider-initiated flow

In this variation the person starts at the company portal, clicks a Jenkins tile, and the IdP sends a ready-made assertion to Jenkins without any request from Jenkins. It feels faster, but it has a security cost: Jenkins receives an answer to a question it never asked, so it cannot match the assertion with a request. Many security teams prefer the SP-initiated flow for exactly this reason, and many organisations disable the IdP-initiated variant for sensitive tools.

Everything in SAML security comes down to one question: why should Jenkins believe this message? The answer is a chain of checks.

What lives inside an assertion

An assertion is a small structured document. Without needing to read the raw XML, you can think of it as having five sections: who issued it, who the subject is, the conditions under which it is valid, a statement about how the person authenticated, and the attribute statement with extra facts such as groups.

The checks Jenkins performs

Certificates and key rotation

The trust relationship is built on certificates. The IdP signs with a private key that never leaves it, and Jenkins holds the matching public certificate. Certificates expire, commonly after one to three years. When the IdP rotates its signing certificate and Jenkins still trusts only the old one, every login fails at the same instant. This is one of the most common causes of a sudden, company-wide Jenkins login outage, and it is entirely preventable with a calendar reminder and a metadata URL that refreshes automatically.

To integrate SAML safely you need a clear picture of where it plugs into Jenkins and what it leaves untouched.

The two security pillars

Every Jenkins controller has a Security section in its global settings with two independent choices. The first is the security realm, which is the source of truth for identities. Typical realms are the built-in user database, an LDAP directory, or a plugin-provided realm such as SAML or OpenID Connect. The second is the authorization strategy, which decides permissions. Typical strategies are anyone-can-do-anything (never appropriate for production), logged-in-users-can-do-anything, matrix-based security, project-based matrix security, and role-based strategy from a plugin.

flowchart LR
    A["User Browser"] --> B["Jenkins Web Layer"]
    B --> C["Security Realm: SAML Plugin"]
    C --> D["Authenticated User + Groups"]
    D --> E["Authorization Strategy: Matrix or Role Based"]
    E --> F{"Permission granted?"}
    F -->|"Yes"| G["Jobs, Nodes, Credentials, Settings"]
    F -->|"No"| H["Access Denied Page"]
        

Users are created on first login

When a person signs in through SAML for the first time, Jenkins creates a lightweight user record for them, based on the attributes in the assertion. This record holds things such as the display name, the email, and any API tokens the person creates later. It does not hold a password. Because Jenkins builds this record only after the first login, an administrator cannot assign permissions to a specific person before that person has ever signed in, but can always assign permissions to a group name, which is the recommended approach anyway.

Where the Jenkins home directory fits

Jenkins keeps its settings, user records and job history in a directory on disk called the Jenkins home. The realm choice, the IdP metadata and the plugin options are all stored there. This matters for backups and recovery: if you restore an old copy of this directory, you also restore the old identity settings, which can silently break logins if the IdP certificate has changed since.

Jenkins itself does not speak SAML. The capability comes from a plugin, which is a downloadable extension installed through the plugin manager.

What the plugin does

The SAML plugin, published in the Jenkins ecosystem under the short name saml, adds a new choice to the security realm list called SAML 2.0. Internally it relies on a well-known open source security library to build authentication requests, parse assertions and verify signatures. This is a good sign: the hard cryptographic work is done by a widely reviewed library instead of custom code, and it also means that plugin and library updates are important security updates for you to install.

The settings you will meet

The plugin exposes a small, focused set of options. Learning their purpose now will make the configuration chapter feel like a checklist instead of a mystery.

Most failed SSO rollouts fail in planning, not in configuration. An hour of careful decisions saves days of recovery.

Decisions to make first

Prerequisites checklist

The IdP must be told about Jenkins before Jenkins can be told about the IdP. Every vendor uses different screens, but the same seven ideas appear in all of them.

Vendor flavours at a glance

With the IdP ready, we can switch Jenkins over. The safest approach is deliberate, ordered and reversible.

This is the chapter where SSO becomes useful. Authentication gets people in the door; group mapping decides which rooms they can enter.

How a group becomes a permission

When Jenkins reads the group attribute from the assertion, it turns every value into an authority attached to that person for the length of the session. The authorization strategy then treats each authority like a named group. A rule that says “grant read access to the group build-viewers” will match any person whose assertion contained the value build-viewers. The match is by exact text, including letter case, so the names must be identical on both sides.

flowchart TD
    A["Directory Group: jenkins-admins"] --> B["IdP releases group attribute"]
    C["Directory Group: team-payments-dev"] --> B
    D["Directory Group: build-viewers"] --> B
    B --> E["Signed SAML Assertion"]
    E --> F["Jenkins SAML Plugin reads authorities"]
    F --> G["Global Matrix: admins get full control"]
    F --> H["Role Strategy: developers get job build and read"]
    F --> I["Folder Permissions: team sees only own folder"]
        

Choosing an authorization strategy

A sound group model

Group changes are not instant

Group memberships arrive inside the assertion at login time. If someone is added to or removed from a group, Jenkins learns about it only at that person’s next login. A removed person with an active Jenkins session keeps the old rights until the session ends or the maximum authentication lifetime expires. This is why the lifetime setting is a real security control and not just a convenience setting.

A login is only the start of the story. What happens over the next hours, and at logout, decides how safe the integration really is.

Two sessions, not one

After a successful login there are actually two separate sessions. The IdP has its own session with the browser, which is what makes the next application login feel instant. Jenkins has a second, independent session of its own. Ending one does not automatically end the other, and that gap is the source of many surprises.

What logout really does

When a person clicks log out in Jenkins, Jenkins ends its own session. Whether the IdP session also ends depends on configuration. If it does not, the very next click on a Jenkins link will silently sign the person back in, which confuses users into thinking logout is broken. The fix is to send people to the IdP logout page after Jenkins logout, or to accept and explain the behaviour. Full single logout, where one logout propagates to every application, is part of the standard but is harder to make reliable, so many organisations rely on short session lifetimes instead.

Choosing the right lifetime

A short maximum lifetime forces frequent re-authentication and quickly reflects group changes, but it annoys people who keep a Jenkins dashboard open all day. A very long lifetime is comfortable but keeps stale permissions alive. A typical balanced choice for engineering teams is one working day, with sensitive controllers using shorter values. Whatever you choose, make sure it matches the session policy that the security team applies at the IdP, so that people do not experience two different clocks.

SAML is designed for humans with browsers. Yet a large part of Jenkins traffic is not human at all.

Who talks to Jenkins without a browser

How API tokens fit in

After a person has signed in through SAML at least once, they can create personal API tokens from their own user page. A token is a long random secret that stands in for the person when calling the Jenkins API. It carries exactly the permissions that the person’s groups grant, so a viewer’s token can only view. Tokens can be named, listed and revoked individually, which is much safer than sharing a password.

Service identities

For shared automation, do not borrow a real person’s token. Create a dedicated service account in the IdP, give it its own narrowly scoped group, sign in once so Jenkins creates the user record, and issue the token from that record. When the automation owner changes, the token remains valid, and the audit trail clearly shows that actions came from a machine.

SAML gives you a strong foundation, but a foundation is not a finished building. These are the areas where careful teams add extra protection.

Reverse proxies and load balancers

Most production Jenkins servers sit behind a reverse proxy or a load balancer that terminates HTTPS. If the proxy does not pass the original host name and protocol to Jenkins, Jenkins may build a callback address with the wrong scheme or host, and the IdP will refuse to return the user there. Make sure the proxy forwards the standard forwarded headers, and confirm that Jenkins shows no reverse proxy warning on its administrative monitors.

Other Jenkins protections that still apply

SAML does not replace the rest of Jenkins security. Keep cross-site request forgery protection enabled, limit which agents can run builds on the controller, restrict script console access to a tiny administrator group, and manage credentials through the credentials system with folder-level scoping. An attacker who cannot log in can still hurt you through an exposed script console or a leaked token, so treat identity as one layer among several.

An SSO integration that nobody watches is a time bomb. A few well-chosen signals turn surprises into scheduled work.

What to record

Useful health signals

Auditing who can do what

Schedule a periodic access review, for example quarterly. Export the members of each Jenkins-related IdP group and ask each group owner to confirm every name. Compare the administrator group against the list of people who actually need it. Reviews sound tedious, yet they are among the cheapest and most effective controls, and auditors specifically ask for evidence of them.

Connecting a login to a build

Because every user is a named identity, build history shows exactly who started or approved each job. This makes it possible to answer questions such as who triggered the release that failed at midnight, using nothing more than the normal Jenkins build page and the central logs.

When SAML breaks it feels mysterious, but the failure almost always falls into a short list of categories. A calm, structured approach finds it quickly.

flowchart TD
    A["Login fails"] --> B{"Does the browser reach the IdP login page?"}
    B -->|"No"| C["Check Jenkins URL, SP Entity ID, IdP endpoint in metadata"]
    B -->|"Yes"| D{"Does the browser return to Jenkins?"}
    D -->|"No"| E["Check ACS address registered at IdP, proxy headers, HTTPS"]
    D -->|"Yes, with error"| F{"What does the Jenkins log say?"}
    F -->|"Signature problem"| G["Certificate rotated or wrong metadata"]
    F -->|"Time problem"| H["Clock drift between servers"]
    F -->|"Audience problem"| I["Entity ID mismatch"]
    D -->|"Yes, but no rights"| J["Group attribute name, values or IdP release wrong"]
        

Useful debugging habits

Capture the actual assertion using a browser extension or the developer tools network tab in a test account, and inspect which attribute names and values it contains. Raise the Jenkins log level for the SAML plugin temporarily, reproduce the failure once, then turn the level back down so logs do not fill the disk or expose personal data. Treat captured assertions as sensitive, because they may contain personal information.

Teams that have run SSO for years tend to converge on the same good habits and repeat the same mistakes. Learning both saves you time.

Patterns that work

A single Jenkins with SAML is simple. A company with many controllers, an outage plan and a disaster recovery drill needs a little more thinking.

Many controllers, one identity provider

Large organisations often run dozens of Jenkins controllers, one per business unit or environment. Each controller is a separate service provider with its own Entity ID and its own callback address, and each must be registered at the IdP. Automating this registration through the IdP’s administrative interface, or using a shared template, prevents mistakes such as two controllers accidentally sharing an identifier, which can cause assertions to be accepted by the wrong system.

flowchart LR
    IDP["Company Identity Provider"] --> J1["Jenkins Team A"]
    IDP --> J2["Jenkins Team B"]
    IDP --> J3["Jenkins Release"]
    IDP --> J4["Jenkins Staging"]
    G["Directory Groups"] --> IDP
    M["Central Logs and Alerts"] -.-> IDP
    M -.-> J1
    M -.-> J2
    M -.-> J3
        

Availability: what if the IdP is down?

Because Jenkins trusts the IdP for every new login, an IdP outage means nobody can start a fresh session. People who are already signed in continue to work until their sessions expire, and builds that are already scheduled keep running, since machine-to-machine traffic uses tokens. To limit the impact, use an IdP with a strong availability record, keep session lifetimes reasonable so that short outages are absorbed, and have a documented emergency procedure for administrators.

The break-glass procedure

Every SSO design needs a controlled way in when SSO itself fails. In Jenkins, the typical last resort is for a server administrator with access to the machine to temporarily change the security setting stored in the Jenkins home directory back to a simple mode, restart, repair the problem, and then restore the SAML configuration. This is powerful and dangerous, so restrict who holds server access, log every use, and rehearse it in staging so that nobody performs it for the first time during a real crisis.

Backup and restore

Back up the Jenkins home directory regularly and remember that it contains the identity configuration. After a restore, verify that the IdP metadata and the Jenkins URL are still correct for the environment you restored into. A restored production backup placed on a test machine, for example, will still try to send people to the production callback address.

SAML is not the only way to connect Jenkins to a central login. Understanding the alternatives helps you justify your choice.

When SAML is the right choice

SAML is a very strong fit when your organisation already standardised on it for other business applications, when your identity team has existing SAML operational skills, when the IdP is a large enterprise product with mature SAML support, or when audit requirements mention it explicitly. If the same team is choosing greenfield technology and every tool in the company already speaks OpenID Connect, that option may reduce maintenance effort. Both are legitimate; the important thing is that Jenkins joins the same central login as everything else.

The following stories are composites of patterns that repeat across the industry. They show how the ideas of this guide play out in practice.

Every design decision has a cost. Knowing the honest trade-offs lets you defend your choices to both engineers and auditors.

Best practices at a glance

Common mistakes to remember

No. SAML answers who the person is and, optionally, which groups they belong to. Jenkins still needs an authorization strategy to convert those groups into permissions on jobs, agents and settings.

With the SAML realm active, the login screen goes through the IdP, so a parallel local password list is not the normal model. Give service automation its own identities at the IdP and use API tokens, and rely on the documented break-glass procedure for emergencies.

Authentication worked, but authorization did not. Most often the group attribute is empty, named differently from what Jenkins expects, or the person has not been added to the IdP group that Jenkins maps to a permission. Check the authorities on their user page.

Jenkins treats the username as the identity key. A different value means a different user, with none of the old tokens, permissions rules tied to that name or personal settings. Decide the username attribute once and keep it.

No. Agents connect to the controller through their own connection mechanism and secret. SAML is only for people signing in through a browser.

No. Without signature validation anyone able to craft a message could claim to be an administrator. Fix the real mismatch instead of weakening the control.

At the person’s next SAML login. An active session keeps the old rights until it ends or the maximum authentication lifetime runs out, so set that lifetime deliberately.

The person can no longer sign in, but tokens on their user record may still work until revoked or the user is removed. Include token cleanup in offboarding and review stale tokens periodically.

Signing is essential; encryption is optional and worthwhile when assertions carry sensitive attributes or when policy requires it. Over HTTPS the assertion is already protected in transit, but encryption also hides it from the browser and any tools running there.

A single controller normally has one security realm and therefore one IdP. Organisations with several identity sources usually federate them behind one central IdP or broker, and let Jenkins trust only that one.

Rehearse on a staging controller, pre-authorise an administrator group, keep an admin session open during the switch, test as an ordinary non-admin user, and have the IdP owner available during the change window.

Integrating Jenkins with SSO through SAML 2.0 means moving the question “who are you?” out of the build server and into the one system that is designed to answer it well. Jenkins keeps ownership of what people may do, using groups delivered by the IdP. When the design is careful, with stable usernames, group-only permissions, a staging rehearsal, monitored certificates, proper service identities and a rehearsed emergency path, the result is a build platform that is easier to use, easier to audit and much harder to misuse. The technology is only half of the work; the other half is the collaboration between the Jenkins platform team and the identity team.