Symptoms

I am not able to log-in to Jenkins using LDAP
LDAP groups are not recognized by Jenkins
In /whoAmI LDAP groups do not appear
I attempted to Configure the LDAP Plugin and I’m locked out of Jenkins
I am receiving a UnknownHostException: DomainDnsZones error

Diagnosis/Treatment

Pre-conditions:
When configuring the LDAP Plugin for the first time the login does not work.
During testing, you should set the Authorization schema to: Anyone can do anything. Otherwise, an incorrect configuration can prevent you from login. See Disable Security.

Minimum Configuration Setup

Ideally, you will want to begin with a simple scenario for CloudBees Jenkins and your LDAP Server for testing purposes

When working with the LDAP plugin for the first time, you should only configure the fields represented in the image below. Notice that an incorrect setting in the User filter field might prevent the user from login.

The only options which should be filled are ( red are mandatory and orange optional):

a - Server as ldap(s)://<IP_ADDRESS>[:<PORT>] Note: Default TCP and UDP are 389 for ldap and 636 for ldaps. Use :<PORT> if the service is exposed in a different port than defaults ones.
b - rootDN ( or <searchbase>)
c - User search filter : Depending on your LDAP Server configuration, there might be three different options which might work - if you don’t know how your LDAP tree is configured, then you might want to test all of them, or consult your Directory Services Administrator.
cn={0}
uid={0}
sAMAccountName={0} (For configuring the LDAP Plugin with an AD server)
d - In the case that the LDAP server(s) do NOT allow Anonymous binding Manager DN & password (or <binddn> & <passwd>) may be needed.

Validate the LDAP Plugin configuration

After configuring the minimum settings, click on Test LDAP Settings.

Once your configuration is validated, log-in with a “UserX” and browse to http://<JENKINS_URL>/whoAmI/ then validate that the groups for “UserX” are correctly retrieved.

If The Configuration Does Not Work…

Check your connection values with a LDAP Client

LDAP client tools, such as JExplorer, might be useful to validate minimum configuration used to integrate LDAP in Jenkins.

On the other hand, this tool can be used, amongst other things, for validating groups members or for validating specific fields like <binddn> (manager DN). In the following example, for “exampleUser” as “uid=colin=people,dc=example,dc=com”.

Use ldapsearch

Validate if you can connect to the LDAP Server from the Jenkins Servers with the help of the ldapsearch command line:

ldapsearch -LLL -H ldap://<IP_ADDRESS>:<PORT> -M -b "<searchbase>" -D "<binddn>" -w "<passwd>" "(uid=<userid>)"

Note:
* For testing purposes you will need to install ldapsearch on the same server running Jenkins. For linux, ldapsearch is included within the ldap-utils package.
* Take care to escape special character with \ in case it is necessary.
* For the following commands, in the case you want to mask your password, -w "<passwd>" can be replaced by:
* -W, which will prompt you to enter your password.
* -y ./pass.txt, so that /pass.txt contains your credentials.

Examples

Retrieve a full organization

ldapsearch -LLL -H ldap://ldap.example.com:389 -M -D "ou=people,dc=example,dc=com" -b "dc=example,dc=com" -w "pass"`

Retrieve one user

ldapsearch -LLL -H ldap://ldap.example.com:389 -M -D "ou=people,dc=example,dc=com" -b "dc=example,dc=com" -w "pass" uid="exampleUser"

Logging

After configuring minimum set-up for the plugin, to troubleshoot specific issues you could create a LDAP dedicated logs including the following packages:

org.acegisecurity.ldap = ALL
org.acegisecurity.providers.ldap = ALL

UnknownHostException: DomainDnsZones Error

2019-03-27 09:08:04.661+0000 [id=2298737]   WARNING h.s.LDAPSecurityRealm$LDAPAuthenticationManager#authenticate: Failed communication with ldap server.
java.net.UnknownHostException: DomainDnsZones

Why the error is thrown:

Active Directory servers are integrated with DNS, and modify entries in the DNS server. They refer to themselves in the root of their LDAP tree. If the Jenkins server is pointed to the root of the LDAP tree, and follow referrals is turned on (which is the default in the LDAP Plugin, then the following takes place:

The application will search for users.
AD server will respond with users and the referral that’s in the root of the LDAP tree, because there could be more users over there.
The application will follow the referral.

This will result in:

A DNS lookup of the base DN ( dc=example,dc=com means a lookup for example.com)
A connection to port 389 or 636 at example.com, which is back to the same server.
The application will continue and read the rest of the objects in the domain as normal.

Problems like this are most commonly caused by the server that the Jenkins application is running on not having the same DNS server as the Active Directory server.

Diagnostic Steps

Change the port number you are attempting to connect with. If you were using port 389 change it to 3268
If you were using port 636 change it to 3269. This may work because a global catalog server returns referrals on 389 to refer to the greater AD “forest”, but acts like a regular LDAP server on 3268 (and 3269 for LDAPS).

Configure the server that the Jenkins application is running on to use the DNS server that the Active Directory server is integrated with.

Double check if the DNS server address has been changed recently. Since DNS server record the Jenkins applications information, please delete the Jenkins application address information from the DNS server to resolve the issue.

If this is not possible, disable Follow Referrals by not using the LDAP Plugin and instead using the Active Directory Plugin where this is a system configurable property: -Dhudson.plugins.active_directory.referral.ignore=true

Further Troubleshooting

The Troubleshooting Steps on the LDAP Plugin Wiki are incredibly valuable and in most cases can resolve your issue. If you are still experiencing an issue, please contact support@cloudbees.com to submit a support request.

The latest update of this article has been tested with:

Jenkins LDAP Configuration Troubleshooting