Authentication methods (LDAP, SAML) in Jenkins - Commands & Configuration

Introduction

Jenkins needs to know who you are to keep your projects safe. LDAP and SAML are two ways Jenkins checks your identity so only the right people can use it.

When you want Jenkins to use your company’s existing user list to control access.

When you want users to log in to Jenkins using their corporate email and password.

When you want to avoid creating separate Jenkins accounts for every user.

When you want single sign-on so users log in once and access Jenkins without extra passwords.

When you want to manage user permissions centrally for many tools including Jenkins.

Config File - config.xml

config.xml

<?xml version="1.0" encoding="UTF-8"?>
<jenkins>
  <securityRealm class="hudson.security.LDAPSecurityRealm" plugin="ldap@2.7">
    <server>ldap://ldap.example.com:389</server>
    <rootDN>dc=example,dc=com</rootDN>
    <inhibitInferRootDN>false</inhibitInferRootDN>
    <userSearchBase>ou=users</userSearchBase>
    <userSearch>uid={0}</userSearch>
    <groupSearchBase>ou=groups</groupSearchBase>
    <groupSearchFilter>(member={0})</groupSearchFilter>
    <groupMembershipStrategy class="hudson.security.FromGroupSearchLDAPGroupMembershipStrategy"/>
    <managerDN>cn=admin,dc=example,dc=com</managerDN>
    <managerPasswordSecret>adminpassword</managerPasswordSecret>
    <disableMailAddressResolver>false</disableMailAddressResolver>
  </securityRealm>
  <authorizationStrategy class="hudson.security.FullControlOnceLoggedInAuthorizationStrategy"/>
</jenkins>

This config.xml file configures Jenkins to use LDAP for authentication.

• server: The LDAP server address.
• rootDN: The base directory to search users and groups.
• userSearch: How to find users by their login name.
• groupSearchFilter: How to find groups a user belongs to.
• managerDN and managerPasswordSecret: Credentials Jenkins uses to connect to LDAP.

This setup lets Jenkins check user credentials against the company LDAP server.

Commands

Start Jenkins server so it loads the configuration and runs with LDAP authentication enabled.

Terminal

java -jar jenkins.war

Expected Output

Running from: /home/jenkins/jenkins.war

2024-06-01 12:00:00.000+0000 [id=1]    INFO    org.eclipse.jetty.server.Server#main: Started @12345ms

INFO: Jenkins is fully up and running

Check Jenkins API with admin credentials to verify LDAP authentication works.

Terminal

curl -u admin:adminpassword http://localhost:8080/api/json

Expected Output

{"assignedLabels":[{}],"mode":"NORMAL","nodeDescription":"the master Jenkins node","numExecutors":2,"description":null,"jobs":[],"overallLoad":{},"primaryView":{"name":"All"},"quietingDown":false,"slaveAgentPort":50000,"unlabeledLoad":{},"useCrumbs":true,"useSecurity":true,"views":[{"name":"All"}]}

Legacy command to start Jenkins with simple user for testing (not LDAP). Shows difference from LDAP setup.

Terminal

java -jar jenkins.war --argumentsRealm.passwd.user1=password1 --argumentsRealm.roles.user1=admin

Expected Output

Running from: /home/jenkins/jenkins.war

INFO: Jenkins is fully up and running

User user1 with admin role created

→

--argumentsRealm.passwd.user1 - Sets password for user1

→

--argumentsRealm.roles.user1 - Assigns role to user1

Key Concept

If you remember nothing else from this pattern, remember: LDAP and SAML let Jenkins check user identity using your company’s existing login system.

Common Mistakes

Not setting the correct LDAP server URL or root DN in Jenkins config.

Jenkins cannot find users or connect to LDAP, so login fails.

Verify LDAP server address and base DN exactly match your company’s LDAP setup.

Forgetting to restart Jenkins after changing authentication settings.

Changes do not take effect until Jenkins reloads the config.

Always restart Jenkins after modifying authentication configuration.

Using simple Jenkins user database commands when LDAP or SAML is configured.

These commands do not affect LDAP users and cause confusion.

Manage users in your LDAP or SAML provider, not Jenkins user database.

Summary

Configure Jenkins with LDAP by editing config.xml to connect to your company’s LDAP server.

Start Jenkins so it uses LDAP to check user logins and permissions.

Verify authentication by accessing Jenkins with LDAP user credentials.

Remember to restart Jenkins after any authentication config changes.