Active Directory (AD) Plugin: secure AD integration

Article ID:235472808
2 minute readKnowledge base

Issue

  • How to integrate Active Directory in Jenkins via LDAPS.

  • How to integrate trusted Active Directory domains in Jenkins.

Environment

  • CloudBees Jenkins Enterprise - Managed controller (CJE-MM)

  • CloudBees Jenkins Enterprise - Operations Center (CJE-OC)

  • Jenkins LTS

  • Active Directory (AD) plugin

  • Windows Server 2012 R2

Resolution

The following resolution steps explains the process for integrating a Secure Active Directory with a non-trusted (self-signed) certificate.

On the AD host
Step 1. Install the Active Directory Certificate Services
If Certificate Services are already installed, skip to step 2, below.

  1. Log in to your Active Directory server as an administrator.

  2. Click Start, point to Administrative Tools, and then click Server Manager.

  3. Then Manage > Add Roles and Features.

  4. On the Select Server Roles page, select the Active Directory Certificate Services check box. Click Next twice.

  5. On the Select Role Services page, select the Certification Authority check box, and then click Next.

  6. On the Specify Setup Type page, click Enterprise, and then click Next.

  7. On the Specify CA Type, click Root CA, and then click Next.

  8. On the Set Up Private Key and Configure Cryptography for CA pages, you can configure optional configuration settings, including cryptographic service providers. However, the default values should be fine. Click Next twice.

  9. In the Common name for this CA box, type the common name of the CA, and then click Next.

  10. On the Set Validity Period page, accept the default values or specify other storage locations for the certificate database and the certificate database log, and then click Next.

  11. After verifying the information on the Confirm Installation Selections page, click Install.

Step 2. Obtain the Server Certificate

As explained on Microsoft’s LDAP over SSL (LDAPS) Certificate > Exporting the LDAPS Certificate and Importing for use with AD DS. Note that you need to:

  1. Choose "No, do not export the private key" in step-10

  2. Choose "DER encoded binary X.509 (.CER)" in step-11. This file will be used in the following step.

On the Jenkins host

Requirements: At the network/infrastructure level, the Jenkins instance must be able to connect to your AD services.

Step 3. Install your cert into your Jenkins cacerts

Having your AD cert file, follows steps from B. Adding “certX” to the keystore on the KB How to install a new SSL certificate.

Step 4. Run Jenkins with proper startup parameters

Include the parameters mentioned in How to install a new SSL certificate plus -Dhudson.plugins.active_directory.ActiveDirectorySecurityRealm.forceLdaps=true. So to sum up, the following parameters need to be added:

  • -Djavax.net.ssl.trustStore=<FULL_PATH_TO_JENKINS_CACERTS>

  • -Djavax.net.ssl.trustStorePassword=<PASS_FOR_JENKINS_CACERTS>

  • -Dhudson.plugins.active_directory.ActiveDirectorySecurityRealm.forceLdaps=true

Step 5. Set-up AD plugin in Jenkins in secure mode

Please, take special caution in the Domain Controller field by using a secure port, by default 3269.

As an example: example.com AD config

Step 6. Check the integration is working via LDAPS

Create a Dedicated logger, including hudson.plugins.active_directory.ActiveDirectorySecurityRealm

After trying to Log in with an AD user ("userX" on the below example) using a trusted domain ("192.168.1.80" on the example), expected output for dedicated logger would look like:

nov 18, 2016 5:05:27 PM FINE hudson.plugins.active_directory.ActiveDirectorySecurityRealm$DescriptorImpl bind
Connecting to ldaps://192.168.1.80:3269/
nov 18, 2016 5:05:27 PM FINE hudson.plugins.active_directory.ActiveDirectorySecurityRealm$DescriptorImpl bind
Binding as userX@contoso.com to ldaps://192.168.1.80:3269/
nov 18, 2016 5:05:27 PM FINE hudson.plugins.active_directory.ActiveDirectorySecurityRealm$DescriptorImpl bind
Bound to 192.168.1.80:3269
nov 18, 2016 5:05:28 PM FINE hudson.plugins.active_directory.ActiveDirectorySecurityRealm$DescriptorImpl bind
Connecting to ldaps://192.168.1.80:3269/
nov 18, 2016 5:05:28 PM FINE hudson.plugins.active_directory.ActiveDirectorySecurityRealm$DescriptorImpl bind
Binding as CN=userX,OU=users,OU=support1,DC=example,DC=com to ldaps://192.168.1.80:3269/
nov 18, 2016 5:05:29 PM FINE hudson.plugins.active_directory.ActiveDirectorySecurityRealm$DescriptorImpl bind
Bound to 192.168.1.80:3269
▼

According to those logs, we can conclude that the integration with the trusted Active Directory domain has been done successfully.

References