Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add 1.20 changelog
Wiki Markup
{jenkins-plugin-info:pluginId=ldap}

Note: This plugin was part of the Jenkins core until 1.468. After that, it was split out into a separately-updateable plugin. However, for backwards compatibility purposes, subsequent core releases still bundle the (old) versionit. If you do not use this plugin at all, you can simply disable it.

Table of Contents

Description

This plugin provides yet another way of authenticating users using LDAP. It can be used with LDAP servers like Active Directory or OpenLDAP among others. Supported configuration can be found below these lines. 

Info

It is strongly encouraged that you upgrade to at least version 1.15 of the LDAP plugin as that version includes the Test LDAP settings button which contains a number of important diagnostic checks to validate subtle issues with your LDAP configuration.

Existing LDAP users are strongly encouraged to upgrade to this version and use the button to ensure that their existing configuration does not have subtle issues (most common subtle issues revolve around group resolution and user lookup and typically surface for users as issues with API token or Jenkins CLI access but can also appear with features such as the Authorize Project plugin or other plugins that require details of user permissions or group membership outside of a user's web session)

 

Configuration

Select LDAP for the Security Realm. You will most likely need to configure some of the Advanced options. There is on-line help available for each option.  Image Removed Image Added

Server

Specify the name of the LDAP server host name (like ldap.acme.org).

...

As of version 1.6, you can specify a list of servers separated by whitespace to provide a fallback if the first server is unavailable, e.g. ldap1.acme.org ldap2.acme.org:1389 or ldaps://ldap1.acme.org:1636 ldap1.acme.org:1389 ldap://ldap2.acme.org ldap3.acme.org

Test LDAP Settings

This button will allow you to check the full LDAP configuration settings which you have defined (as compared with the field validation which only verifies a subset of the configuration)

Clicking this button will display a modal dialog to prompt you to provide a username and password:

Image Added

There are a number of tests that you should perform before saving a new / modified security configuration:

  • Enter your own username & password to validate that you will still be able to login after the security settings have been applied => You do not want to lock yourself out
  • Ideally get a couple of other users to try their username & password to ensure that other users can login. If you cannot get other users to come to your computer, you can at least verify that Jenkins can resolve their accounts by using their username and an empty password => You do not want to lock legitimate users out
  • In most cases, you will be using LDAP groups, so ensure that you verify reverse group lookup by testing with a user account that is a member of at least one group (do not forget the empty password trick to perform lookup). If there are important groups for your Jenkins instance, try using at least one user for each important group => You want to ensure that group lookup functions correctly.

(warning) NOTE it is quite likely that existing installations may have subtle issues with group resolution, it is recommended that you validate your group resolution with the new button functionality after upgrading the LDAP plugin to 1.15 as there is a good chance that it will catch problems you didn't really know you had!

Root DN

For authenticating user and determing determining the roles given to this user, Jenkins performs multiple LDAP queries.

...

As of 1.7 of the LDAP plugin, you can now specify additional Environment Properties to provide the backing Java LDAP client API. See Oracle's documentation for details of what properties are available and what functionality they provide. As a minimum you should strongly consider providing the following

Property Name

Description

com.sun.jndi.ldap.connect.

timeou

timeout

This is the socket connection timeout in milliseconds. If your LDAP servers are all close to your Jenkins server you can probably set a small value, e.g. 5000 milliseconds. Setting a value smaller that this may result in excessive timeouts due to the TCP/IP connection establishment retry mechanism.

com.sun.jndi.ldap.read.timeout

This is the socket read timeout in milliseconds. If your LDAP queries are all fast you can probably set a low value. The value is ignored if the Jenkins Master is running on Java 1.5. A reasonable default is 60000 milliseconds.

Troubleshooting

The following script Groovy script can be useful when trying to determine if whether you have group search configured correctly:

Code Block
     String[] names = ["a group name","a user name","a name that does not exist"];
    for (name in names) {
      println("Checking the name '" + name + "'...")
      try {
        println("  It is ana USER: " + Jenkins.instance.securityRealm.loadUserByUsername(name))
        println("  Has groups/authorities: " + Jenkins.instance.securityRealm.loadUserByUsername(name).getAuthorities())
      } catch (Exception e) {
          try {
            println("  It is a GROUP: " + Jenkins.instance.securityRealm.loadGroupByGroupname(name))
            println("")
            continue
          } catch (Exception e1) {
            println("  It is NOT a group, reason: " + e1.getMessage())
          }
        println("  It is NOT ana user, reason: " + e.getMessage())
      }
      println("");
    }
  • If login attempts result in "OperationNotSupportedException - Function Not Implemented", "Administrative Limit Exceeded" or similar error, the LDAP query to determine the group membership for the user may be triggering this. First try setting the "Group search base" setting as specific as possible for your LDAP structure, to reduce the scope of the query. If the error persists, you may need to edit the WEB-INF/security/LDAPBindSecurityRealm.groovy file that is included in jenkins.war. Change the line with groupSearchFilter = "(| (member={0}) (uniqueMember={0}) (memberUid={1}))"; to query only of the field used in your LDAP for group membership, such as groupSearchFilter = "(member={0})"; (then restart Jenkins).
  • The LDAP groups were available in Jenkins in the format of ROLE_Uppercasedgroupname, so the developers ldap group would be ROLE_Developers in Jenkins, but since 1.404 they are available as is: no prefix or upper casing,
  • Since Jenkins 1.468, this has been moved to a plugin. The LDAPBindSecurityRealm.groovy file is therefore part of the ldap.jpi file. You can find the default template at $JENKINS_HOME/plugins/ldap/WEB-INF/classes/hudson/security/LDAPBindSecurityRealm.groovy. That file will be recreated from the ldap.jpi file every time Jenkins starts, so if you need to override the defaults, the correct way is to just copy the template file to $JENKINS_HOME/LDAPBindSecurityRealm.groovy. The $JENKINS_HOME/LDAPBindSecurityRealm.groovy file is re-read every time the security components are reconfigured, so it should just be a case of re-saving the security configuration to force the file to be re-read.
  • If you are using this plugin and not the Active Directory plugin to connect to Active Directory, you will need to change the Group Search Filter to filter to: 
    {{(& (cn={0}) (objectclass=group) ) }} and change the Group Membership Filter to: (member={0}).   If you want AD to return nested group membership then change the Group Membership Filter to: (member:1.2.840.113556.1.4.1941:={0})

Performance Tuning

Here is a checklist to help improve performance:

...

  • User search filter: sAMAccountName={0}
  • Group search filter: (&(objectclass=group)(cn={0}))
  • Group membership, one of
    • Search for groups containing user (if nested group membership required)
      • Group membership filter: (&(objectCategory=group)(member:1.2.840.113556.1.4.1941:={0}))
    • Parse user attribute for list of groups (if nested group membership not required this will be faster)
      •  Group membership attribute: memberOf

Version History

Version 1.20 (19th Feb 2018)

  • JENKINS-48917: Add option to ignore specific LDAP domains in the event of a connection failure.
  • Add compatibility warning when upgrading from 1.15 or older due to configuration format changes in 1.16.

Version 1.19 (31st Jan 2018)

  • JENKINS-21784: Add support for querying membership of LDAP groups.
  • Log communication failures with LDAP servers as warnings in the hudson.security.LDAPSecurityRealm logger.

Version 1.18 (9th Nov 2017)

  • Upgrade to new parent pom (2.36).
  • Update test text to match UI
  • Updated baseline version of Jenkins to 1.651.3

Version 1.17 (13th Sep 2017)

Version 1.16 (3rd July 2017)

  • JENKINS-21475 Added ability to configure multiple LDAP configurations to connect to LDAP servers with different schemes etc.
  • JENKINS-43994 When the user can login but lookup fails report this as a potential issue for API tokens and SSH key base authentication of the user.

Version 1.15 (2nd May 2017)

  • Updated baseline version of Jenkins to 1.625.3
  • Added some tests that actually connect to an LDAP server to help prevent regressions
  • JENKINS-21374 Allow disabling ROLE_ prefixed role creation
  • JENKINS-43388 Added a validation button that allows for validation of the complete LDAP configuration
    • Fixed a bug in authorities population identified by the new validation button

Version 1.14 (23rd Jan 2017)

  • Fixed JENKINS-30588: Value for "Group membership attribute" not saved.

Version 1.13 (20th Sep 2016)

  • Fixed JENKINS-8152: The rootDN is now URI-encoded when included in the provider URL. If upgrading from previous versions, please take this into account if the value had been manually encoded.

Version 1.12 (26th Apr 2016)

  • Upgrade to new parent pom.
  • Integrate Findbugs and fix potential errors discovered by the plugin.

Version 1.11 (3rd Oct 2014)

  • Performance improvements especially in the presence of lots of requests with HTTP basic auth.

...

  • Turned the group membership lookup into a strategy. There are now two strategies, the default "look up groups containing the user" strategy and an experimental new strategy which looks for an attribute in the user's LDAP record that contains a list of DNs of the groups that the user belongs to. Rumour has it that this second strategy may actually provide faster performance for Active Directory, but as the person who wrote this code does not have an Active Directory instance to test against - until some kind soul tests, confirms and edits this text to remove the assertion that this is a rumour - using the new strategy is Caveat emptor.

Wiki Markup*\[Update 23/05/2014\] Some  Some kind testers have confirmed that the new strategy seems to work against Active Directory... but as those testers did not have performance issues to start with, again it is just a rumour that there is a performance increase\! Version 1.10.2 is recommended to fix two non-critical but annoying NPEs with the new strategy{*}

Version 1.9 (9th May 2014)

  • Added some interim hacks to work around JENKINS-22247. Setting the temporary system properties 

    No Format
    
    hudson.security.LDAPSecurityRealm.forceUsernameLowercase=true
    

    and 

    No Format
    
    hudson.security.LDAPSecurityRealm.forceGroupnameLowercase=true
    

    will enable these hacks. These system properties will be removed in a future version once the core issue has been resolved.

  • Modernised the configuration screen Jelly to use current form-binding.
  • The manager password is now correctly encrypted using Secret. This is a downgrade breaking change. WARNING! If you upgrade to 1.9 and then downgrade, the manager password may be lost from your configuration. 

Version 1.8 (17th Jan 2014)

Older versions

Look at the commit history for details of the changes in older versions. (SC - If you want to update this wiki page with those details as a service to the community please feel free to do so, this page was missing any version history, so I added at least some history)

Version 1.7 (9th Dec 2013)

  • Fixed JENKINS-16443
  • Add ability to define LDAP environment properties.

Version 1.6 (24th Jul 2013)

  • Add support for multiple servers.

Version 1.5 (14th Jun 2013)

Version 1.4 (24th Apr 2013)

  • Move userDetails caching into the user details service to avoid callers bypassing the cache.

Version 1.3 (24th Apr 2013)

  • Add Chinese (traditional) translation.
  • Update .gitignore.
  • Add an optional caching mechanism for loadByUsername and loadGroupByGroupName.

Version 1.2 (6th Dev 2012)

  • Added .gitignore.
  • Update Surefire version.
  • Add "Disable Ldap Mail Resolver" checkbox/functionality.

Version 1.1 (11th Jun 2012)

  • Explicitly set the classloader so that classes in the plugin do not fail to resolve.
  • Complete pom.xml.

Version 1.0 (6th Jun 2012)

  • Initial release.