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.

Practice

1. What is the main purpose of using LDAP authentication in Jenkins?

easy

A. To connect Jenkins to an existing directory server for user login

B. To enable Jenkins to send emails automatically

C. To create new user accounts inside Jenkins manually

D. To backup Jenkins configuration files

Solution

1. Step 1: Understand LDAP role in Jenkins

   LDAP allows Jenkins to use an external directory server for user authentication instead of managing users internally.

2. Step 2: Identify the correct purpose

   Connecting Jenkins to an existing directory server helps reuse user accounts and centralize login management.

3. Final Answer:

   To connect Jenkins to an existing directory server for user login -> Option A

4. Quick Check:

   LDAP = External directory login [OK]

Hint: LDAP connects Jenkins to directory servers for login [OK]

Common Mistakes:

• Confusing LDAP with email or backup functions
• Thinking LDAP creates users inside Jenkins
• Mixing LDAP with SAML single sign-on

2. Which of the following is the correct Jenkins configuration snippet to enable LDAP authentication?

easy

A. securityRealm {
ldap {
server 'ldap://ldap.example.com'
}
}

B. securityRealm {
saml {
idp 'https://idp.example.com'
}
}

C. securityRealm {
local {
users ['admin']
}
}

D. securityRealm {
oauth {
provider 'github'
}
}

Solution

1. Step 1: Identify LDAP configuration syntax

   The snippet with ldap and server 'ldap://...' matches LDAP setup in Jenkins.

2. Step 2: Exclude other authentication methods

   Options with saml, local, or oauth are for different authentication types, not LDAP.

3. Final Answer:

   securityRealm { ldap { server 'ldap://ldap.example.com' } } -> Option A

4. Quick Check:

   LDAP config uses ldap { server } [OK]

Hint: LDAP config uses 'ldap { server "ldap://..." }' block [OK]

Common Mistakes:

• Confusing LDAP with SAML or OAuth syntax
• Using local user config for LDAP
• Missing the ldap server URL

3. Given this Jenkins SAML configuration snippet, what will happen when a user tries to log in?

securityRealm {
  saml {
    idp 'https://idp.example.com'
    usernameField 'email'
  }
}

medium

A. Users must enter their LDAP password to log in

B. Jenkins will authenticate users via the specified identity provider using their email as username

C. Jenkins will ignore the SAML config and use local users

D. Jenkins will fail to start due to syntax error

Solution

1. Step 1: Analyze SAML configuration

   The snippet sets Jenkins to use SAML authentication with an identity provider URL and specifies the username field as 'email'.

2. Step 2: Understand login behavior

   Users will be redirected to the identity provider for login, and their email will be used as the Jenkins username.

3. Final Answer:

   Jenkins will authenticate users via the specified identity provider using their email as username -> Option B

4. Quick Check:

   SAML uses IdP and usernameField [OK]

Hint: SAML uses IdP URL and usernameField for login [OK]

Common Mistakes:

• Assuming local or LDAP login instead of SAML
• Confusing usernameField with password
• Thinking this causes startup failure

4. You configured Jenkins with LDAP authentication but users cannot log in. Which of these is the most likely cause?

medium

A. The Jenkins server has no internet connection

B. The Jenkins home directory is missing

C. The Jenkins user database is empty

D. The LDAP server URL is incorrect or unreachable

Solution

1. Step 1: Identify common LDAP login issues

   If users cannot log in with LDAP, a frequent cause is that Jenkins cannot reach the LDAP server due to wrong URL or network issues.

2. Step 2: Exclude unrelated causes

   Internet connection is not always required if LDAP is internal; empty Jenkins user DB is irrelevant with LDAP; missing home directory causes other errors.

3. Final Answer:

   The LDAP server URL is incorrect or unreachable -> Option D

4. Quick Check:

   LDAP login fails if server URL wrong [OK]

Hint: Check LDAP server URL first if login fails [OK]

Common Mistakes:

• Blaming Jenkins user DB when LDAP is used
• Assuming internet is always needed
• Ignoring network connectivity to LDAP

5. You want Jenkins to allow users to log in using SAML with your company's identity provider and also fallback to LDAP if SAML fails. Which approach is best?

hard

A. Configure LDAP first and then SAML, Jenkins will try both automatically

B. Use only LDAP because Jenkins does not support multiple authentication methods

C. Configure SAML as primary and LDAP as secondary authentication in Jenkins security settings

D. Set up two separate Jenkins instances, one for SAML and one for LDAP

Solution

1. Step 1: Understand Jenkins authentication chaining

   Jenkins supports configuring multiple authentication methods with priority, allowing fallback from SAML to LDAP.

2. Step 2: Choose correct configuration order

   Setting SAML as primary and LDAP as secondary lets Jenkins try SAML first, then LDAP if SAML fails.

3. Step 3: Exclude incorrect options

   Only LDAP is limiting; Jenkins can chain methods; separate instances add complexity; LDAP first then SAML is not standard fallback order.

4. Final Answer:

   Configure SAML as primary and LDAP as secondary authentication in Jenkins security settings -> Option C

5. Quick Check:

   Primary SAML with LDAP fallback = Configure SAML as primary and LDAP as secondary authentication in Jenkins security settings [OK]

Hint: Set SAML primary, LDAP secondary for fallback [OK]

Common Mistakes:

• Thinking Jenkins cannot chain authentication methods
• Using separate Jenkins instances unnecessarily
• Configuring LDAP before SAML for fallback