Active Directory plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID active-directory Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
1.41 (archives)
Jun 04, 2015
mailer (version:1.5)
Source Code
Issue Tracking
Pull Requests
Open Issues
Pull Requests
Kohsuke Kawaguchi (id: kohsuke)
Usage Installations 2014-Nov 11447
2014-Dec 11462
2015-Jan 11877
2015-Feb 12212
2015-Mar 12844
2015-Apr 12915
2015-May 13039
2015-Jun 13482
2015-Jul 13754
2015-Aug 13718
2015-Sep 14269
2015-Oct 14582

With this plugin, you can configure Jenkins to authenticate the username and the password through Active Directory. This plugin internally uses two very different implementations, depending on whether Jenkins is running on Windows or non-Windows and if you specify a domain.

  • If Jenkins is running on a Windows machine and you do not specify a domain, that machine must be a member of the domain you wish to authenticate against. Jenkins uses ADSI to figure out all the details, so no additional configuration is required.
  • If Jenkins is running on a non-Windows machine (or you specify one or more domains), then you need to tell Jenkins the name of Active Directory domain(s) to authenticate with. Jenkins then uses DNS SRV records and LDAP service of Active Directory to authenticate users.

Jenkins recognizes all the groups in Active Directory that the user belongs to, so you can use those to make authorization decisions (for example, you can choose the matrix-based security as the authorization strategy and perhaps allow "Domain Admins" to administer Jenkins).

Securing access to Active Directory servers

Active Directory plugin performs TLS upgrade — it connects to domain controllers through insecure LDAP, then from within the LDAP protocol it "upgrades" the connection to use TLS, achieving the same degree of confidentiality and server authentication as LDAPS does.

As the server needs to have a valid X509 certificate for this to function, if the server fails to do TLS upgrade, the communication continues to happen over insecure LDAP. In other words, in the environment that the server supports this, it'll automatically use a properly secure connection. See TechNet article for how to install a certificate on your AD domain controllers to enable this feature.

To verify if the connection is upgraded or not, see Logging and adds a logger to hudson.plugins.active_directory.ActiveDirectorySecurityRealm for FINE or above. Search fot "TLS" in the log messages.

If you must insist on using LDAPS, and not TLS upgrade, you can set the system property hudson.plugins.active_directory.ActiveDirectorySecurityRealm.forceLdaps=true as a startup parameter to force Jenkins to start a connection with LDAPS, even though this will buy you nothing over LDAP+TLS upgrade. Example: Add -Dhudson.plugins.active_directory.ActiveDirectorySecurityRealm.forceLdaps=true inside the <arguments> tag in Jenkins.xml. You will also need to check inside config.xml to ensure either the secured port is defined (636 or 3269) or not defined at all.

<SecurityRealm ...> <server>[|:636|:3269]</server></SecurityRealm>

Override domain controllers

This plugin follows the standard lookup procedure to determine the list of candidate Active Directory domain controllers, and this should be sufficient for the normal circumstances. But if for some reasons it isn't, you can manually override and provide the list of domain controllers by specifying the "Domain controller" field in the advanced section with the value of the format "host:port,host:port,...". The port should normally be 3269 (for global catalog over SSL), 636 (LDAP over SSL), 3268 (for global catalog), or 389 (LDAP).

For historical reasons, the system property "hudson.plugins.active_directory.ActiveDirectorySecurityRealm.domainControllers" for this purpose is still supported, but starting with 1.28, the configuration in the UI is preferred.

If you have multiple AD domains federated into a forest, be sure to use a global catalog, or else you will fail to find group memberships that are defined in other domains.

Group Names

If you have added a group and it appears in the list with a red stop sign, Jenkins cannot find it. Remove it and investigate why.

If you are not sure what the notation for a group name is, try the following procedure:

  1. Grant full access to anonymous user (in case you have to reconfigure security having logged out)
  2. Configure the AD server, test it, and save the configuration
  3. Log in using the AD user. Click your name to see a page listing the groups you were found in
  4. Add the relevant groups found to the security matrix with appropriate permissions
  5. Do not forget to withdraw permissions from the anonymous user, taking into consideration the Overall:Read permission (hover over the column header for detail)


If you think you've configured everything correctly but still not being able to login (or any other problems), please enable Logging and configure logging level for "hudson.plugins.active_directory" to ALL. Attempt a login and then file a ticket with the log output.

Warning for 1.37

Be careful if you intend to install version 1.37. It has been known to cause excessive load on Active Directory authentication servers. If you install this version you should carefully monitor traffic on relevant ports, e.g.: tcpdump port 389 or 3268.


Version 1.40 (2015/04/06)

  • De-emphasize custom domain setting in the ADSI mode, but once that's selected, expose a full set of options (JENKINS-27763)

Version 1.39 (2014/11/17)

  • A hack-ish switch to enable faster group lookup (JENKINS-24195)
  • Login based on userPrincipalName (which looks like an email address) was not working

Version 1.38 (2014/06/03)

  • Apparently the "improvement" in 1.37 backfired for some users. Providing an option for them to select the algorithm as a fallback (JENKINS-22830)

Version 1.37 (2014/04/15)

  • Drastically speed up the recursive group membership search through the use of a Microsoft extension in the LDAP filter expression.

Version 1.36 (2014/03/27)

  • Fixed a thread leak problem when running on Windows (JENKINS-16429)

Version 1.35 (2014/03/11)

  • Implemented "remember me" support in conjunction with upcoming Jenkins 1.556. (JENKINS-9258)

Version 1.34 (2014/03/10)

  • Make test-button work for multi-domain configurations (Pull request #7)
  • Fix forceLDAPs system property and fix ports when using the system property (JENKINS-21073)
  • Added form validation check to the ADSI codepath (JENKINS-17923)

Version 1.33 (2013/05/06)

  • Fixed a show-stopper that broke most ADSI deployments (JENKINS-17676)

Version 1.32 (2013/05/01)

  • Fixed a regression in 1.31 that caused encoding problems with ADSI (JENKINS-17692)

Version 1.31 (2013/04/18)

  • Performance improvement.
  • Fixed a bug in handling OU that contains tricky characters like '/'.
  • Ignore the lookup failure for the memberOf group as it's possible that the authenticating user doesn't have permissions to access the group (JENKINS-16205)

Version 1.30 (2012/11/06)

  • NullPointerException encountered while testing connection.

Version 1.29 (2012/06/06)

  • Added additional logging statements for diagnosis.

Version 1.28 (2012/05/07)

  • Fixed a regression in 1.27 JENKINS-13650
  • If an authentication fails (as opposed to a communication problem), don't fallback to other domain controllers to prevent a cascade of login failures, which can result in an account lock out.

Version 1.27 (2012/04/26)

  • Started caching group definitions to reduce the traffic to domain controllers
  • ADSI implementation now more eagerly releases COM objects without waiting for GC
  • Removed bogus error message when an user wasn't found (JENKINS-12619)
  • When attempting anonymous bind, don't pass in the user name to prevent it from counted as a failure in case anonymous bind is disabled (JENKINS-13595)
  • Fixed a bug that broke the handling of exotic group names (JENKINS-12907)
  • Canonicalize the user name as per writtein AD, instead of using what the user gave us (JENKINS-12607)
  • Updated com4j to use ADSI even on 64bit Windows JVMs (JENKINS-11719)

Version 1.26 (2012/01/27)

  • Improved caching on group information (pull #3)
  • The "Test" button in the config page now supports multi-domain test. (pull #2)
  • Honor LDAP timeout setting when talking to domain controllers (pull #1)

Version 1.25 (2012/01/24)

  • Fixed a security vulnerability that affects AD with anonymoud binding enabled.

Version 1.24 (2012/01/05)

  • Fixed a bug in server lookup. We should still consider lower-priority servers if higher priority ones are unreachable
  • Supported group lookup by name
  • Report all attempted authentication when trying to authenticate against multiple domains (JENKINS-11948)

Version 1.23 (2011/11/29)

  • Fixed a poor interaction with the matrix security form check (JENKINS-11720)
  • Fixed a regression in 1.22 that broke the distribution group lookup (JENKINS-11668)

Version 1.22 (2011/11/8)

Version 1.21 (2011/11/4)

  • Plugin shouldn't require a record on the domain
  • Fixed a bug in the TLS upgrade (JENKINS-8132)
  • Plugin was not recognizing the user's primary group ("Domain Users" most typically)
  • E-mail and full name are now propagated to Jenkins (JENKINS-6648)
  • Made to correctly work with CLI username/password authentication (JENKINS-7995)

Version 1.20 (2011/10/19)

  • Fixed a security vulnerability (SECURITY-18)

Version 1.19

  • If we fail to check the account disabled flag, assume it's enabled (JENKINS-10086)
  • If/when the socket factory is given, JRE appears to automatically try to connect via SSL, so we can only do so during StartTLS call.
  • Error only if there's no server (either configured or discovered.)
  • Added the preferred Server functionality back

Version 1.18 (2011/03/20)

  • Add a preferred server in configuration options
  • Update for Jenkins

Version 1.17 (2010/11/16)

  • Look up is now done via LDAPS instead of LDAP (although there's no certificate check done now.)
  • The plugin now talks to the global catalog for efficiency, as opposed to a domain, if that's available.
  • Some DNS returns '.' at the end of the host name. Handle it correctly (JENKINS-2647)
  • Fixed a possible LDAP injection problem (JENKINS-3118)
  • Try all the available servers before giving up. Useful when some of your domain controllers aren't working properly. (JENKINS-4268)
  • Added the site support (JENKINS-4203)
  • Cleaned up the help text that incorrectly stated that this doesn't work on Unix. It works. (JENKINS-2500)

Version 1.16 (2009/12/8)

  • Added a workaround for WebSphere in doing DNS lookup via JNDI (JENKINS-5045)

Version 1.15 (2009/06/10)

  • Fix bug introduced with 1.14 where an AD setup with circular group references would cause a stack overflow.

Version 1.14 (2009/06/02)

  • Support nested groups (via the Unix provider) (JENKINS-3071)
  • Fixed a bug that prevented the "authenticated" role being honoured (JENKINS-3735)
  • Support authenticting against multiple domains (JENKINS-3576)

Version 1.13 (2009/05/19)

  • Fixed a bug that degraded Windows support (which forces you to enter the domain name.)
  • Implementation of group recognition (for displaying group icon in matrix for instance.)

Version 1.12 (2009/04/08)

  • Some DNS returns '.' at the end of the host name. Handle it correctly (JENKINS-2647) (not correctly fixed until 1.17)
  • Fixed NPE in the form field validation when a group name was added (JENKINS-3344)
  • Lookup fails for members of groups with special characters in the name (like '/') (JENKINS-3249)

Version 1.11 (2009/03/25)

  • No change. This is a re-release since 1.10 didn't hit the update center.

Version 1.10 (2009/03/20)

  • On Windows, specifying the domain name in the "advanced" section wasn't taking effect.

Version 1.9 (2009/02/17)

  • Modified to work with 64bit Winddows (report)

Version 1.8 (2009/02/13)

  • Hudson honors the priority in the SRV entries (patch)

Version 1.7 (2009/01/15)

  • Fixed a bug in handling alternative UPN suffix. (discussion)

Version 1.6 (2009/01/12)

  • Fixed a bug in handling "referrals" (which I believe happens when you run AD forest.)

Version 1.5 (2008/06/24)

  • Windows users can now also use the LDAP-based AD authentication (the same code used on Unix.) This is apparently necessary when Hudson runs as a local user instead of a domain user (discussion)

Version 1.4 (2008/06/11)

  • Fixed a bug where the configuration page doesn't show the configured AD domain name
  • Fixed a bug that prevented this from working with user-defined containers

Version 1.3 (2008/06/09)

  • Supported authentication from Hudson running on non-Windows machines

Version 1.2 (2008/02/27)

  • Fixed IllegalArgumentException in remember-me implementation (JENKINS-1229)

Version 1.0 (2007/01/09)

  • Initial version


plugin-user plugin-user Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment