Active Directory (AD) Plugin: secure AD integration

Issue

  • How to integrate Active Directory in Jenkins via LDAPS.
  • How to integrate trusted Active Directory domains in Jenkins.

Environment

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

Note: 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

Have more questions?

1 Comments

  • 1
    Avatar
    Lokesh Kamalay

    Some improvements to consider here:
    1. Enabling Cache: This will help to store the user details for some time resulting in quick authentication and login.
    2. You may also change the "Group Membership Lookup Strategy" to Token-Groups user attribute (based on your strategy)
    3. Check-in "Use Jenkins Internal Database" and provide a user (Mostly admin). This user is able to access the Jenkins when Domain Controller is not responding.

    Migrating from Local to AD:
           If you want to use Existing "Role-based matrix authorization strategy" while switching from Local to AD, you must have the same user id otherwise Jenkins doesn't authorize you.


    To fix this, you may need to edit the nectar file by adding your ID that matches with your AD.
    nectar file location: $JENKINS-OC_HOME/nectar-rbac.xml (a restart is needed)

Please sign in to leave a comment.