DXlink with SSL to ADS using MS Root Certificate for Unicenter Workload Control Center.

Document ID : KB000053442
Last Modified Date : 14/02/2018
Show Technical Document Details

Description

This document details how to configure eIAM ( UWCC r11 ) to connect to ADS via SSL.

Solution

DXlink with SSL to Active Directory using a Microsoft Root Certificate.

This document is produced for a UWCC installation running on the same server as CA Directory.

This document is broken down into the following steps:

  • Download the Microsoft CA Root certificate from the certificate server.
  • Convert to PEM.
  • Update trusted.pem.
  • Generate the new certificates using the command "DXcertgen certs".
  • Create a new DXlink knowledge reference file.
  • Modify the existing knowledge files.
  • Restart DXserver.
  • Setting up the eIAM to use the iTechPoz Router.
  • Check SSL configuration.

Please Note:
Make a backup of the entire "%DXHOME%\eTrust Directory\dxserver\config" folder structure before continuing.

Download the Microsoft CA Root Certificate from the certificate server using fully qualified name.

  • To download the Microsoft Root CA Certificate, you'll need to access the certificate server using the fully qualified domain name. Please use Internet Explorer and navigate to the certificate server name, as illustrated below:

https://FQDN/certsrv

Figure 1

  • Once connected to the certificate server, please click the "Download a CA certificate, certificate chain, or CRL" option.
  • Click the "Base 64" radio button, and click the "Download CA certificate" link.
  • Save the CA certificate into the folder "C:\cert\" folder and keep the default name of "certnew.cer".

Convert to PEM Format

  • Now the CA certificate must be converted into PEM format. This can be done using OPENSSL.

    The OPENSSL installation can be downloaded from the following link:
    http://www.deanlee.cn/downloads/openssl-0.9.8e_WIN32.zip
    Unzip the installation ZIP files, then change directory (CD) to the "{OPENSSL Install Folder}\bin" folder.


  • Once the OPENSSL utility is installed, issue the following command from a command window:

    openssl x509 -in c:\cert\certnew.cer -outform PEM -out c:\cert\certnew.pem

Update the "trusted.pem file

  • Open the "c:\cert\certnew.pem" file with a text editor and copy the certificate contents into the "%DXHOME%\config\ssld\trusted.pem" file.

    Below is an example of the PEM certificate you will be copying into the trusted.pem file.

Figure 2

Below is a copy of a trusted.pem file with the inserted Microsoft root CA certificate marked with blue:

Figure 3

  • Once the Microsoft certificate is pasted into the "%DXHOME%\config\ssld\trusted.pem" file, save the file.

Generate the new certificates using the command "DXcertgen certs"

  • Run the CA Directory command "dxcertgen certs" from a command window. An example of the commands execution is below.

Figure 4

  • Edit the "%DXHOME%\config\ssld\trusted.pem" file.

    The Microsoft CA certificate will now have a tect header beginning with:

                        Certificate:
                                 Data:
                                         Version: 3 (0x2)
                                          Serial Number: 0 (0x0)

  • Highlight from the beginning of the Microsoft CA certificate all the way to the end of the file and copy the highlighted portion. An example of the highlight process is below.
  • Figure 5

  • Paste it to the end of the "%DXHOME%\config\ssld\iTechPoz-trusted.pem" file. Then save the "%DXHOME%\config\ssld\iTechPoz-trusted.pem" file.

Please Note:
If you receive the an error message after issuing the "dxcertgen certs" command, follow the additional instruction below, but only if you get the following error:

DXcertgen Error

C:\>dxcertgen certs
Setting root certificate and public/private keys for signing...
Exporting certificate 'dxcertgen' from
C:\ETRUST~1\dxserver\..\jxplorer\security\cacerts...
alias 'dxcertgen' not found
Generating public and private key pair...
Generating key pair for 'dxcertgen' in
C:\ETRUST~1\dxserver\..\jxplorer\security\cacerts...

dxcertgen certs failed.

Error: ?-1? setRootCertAndKeyPair() failed
Error: ?-8? generateKeyPair() failed
Error: ?-1? keytoolGenerateKeyPair() failed
Error: ?-2? keytool error: java.io.FileNotFoundException:
C:\ETRUST~1\dxserver\..\jxplorer\security\cacerts (The system cannot find the path specified)

Additional Instructions

  1. Take note of the value of the JAVA_HOME variable by running the "env" command.
  2. Issue the command:
                  set JAVA_HOME=
  3. Try to generate the certificates again running the command "dxcertgen certs"
  4. After that set the JAVA_HOME variable with the value you take note before.

Create a new DXlink knowledge reference file

  • Create a new file, called "AD.dxc" with the following content
#
# AD.dxc
#
 
set dsa AD =
{
prefix            = <cn iTechPozRouter><o MSAD>
native-prefix     = <dc com><dc company><dc My-ADS>
dsa-name          = <dc com><dc company><cn MSADS>
dsa-password      = "secret"
ldap-dsa-name     = <dc com><dc company><dc My-ADS><cn Users><cn "Administrator">
ldap-dsa-password = "password_of_user_above"
address           = tcp "ADS_FQDN" port 636
auth-levels       = clear-password
trust-flags       = allow-check-password, no-server-credentials, allow-upgrading
link-flags        = dsp-ldap, ms-ad, ssl-encryption
};
set transparent-routing = true

Please Note:

  1. The "native-prefix, ldap-dsa-name and ldap-dsa-password" must all match the data within your Active Directory server.
  2. It is strongly recommended that you type the text above instead of copying it, as some text editors will use different character formatting, which may cause issues.

Modify the existing knowledge files

  • Edit the file "%DXHOME%\config\knowledge\iTechPoz.dxg" and add the line: source "AD.dxc";
    below the line that reads: source "iTechPoz-XXXX.dxc"; so that the end of the file looks like:

          source "iTechPoz-XXXX.dxc";
          source "AD.dxc";

         Save the file after you've completed the edit.

  • Edit the "%DXHOME%\config\knowledge\iTechPoz-XXXXXXX-Router.dxc" file.
    • Un-comment the line "link-flags = ssl-encryption".
    • At the line "auth-levels = anonymous" append the string ",clear-password". After the edit, the "auth-levels" line will look like:
  •          auth-levels = anonymous, clear-password

    • Save the file and close it.
  • Edit the "%DXHOME%\config\knowledge\iTechPoz-XXXXXXX.dxc" file
    • Un-comment the line "link-flags = ssl-encryption"
    • Save the file and close it.

Restart the CA Directory DSAs (DXserver)

  • Stop the all DSAs and SSLD service using the following commands:
    • dxserver stop all
    • ssld stop all

  • Restart them using the following commands:
    • ssld start all
    • dxserver start all

Setting up the eIAM to use the iTechPoz Router DSA

  • See the screenshot below for the initial connection details. Please note that there is no password required, so the "Password" and "Confirm Password" fields can remain blank. This is due to the fact that eIAM will use the password stored in the iTechPoz Router.

Figure 6

Check if the SSL is working

  • On the machine where the iTechPoz Router DSA is running, open a windows command shell and connect to the iTechPoz Router DSA's console port and set a trace level of "ldap".

telnet localhost 11684
dsa> set trace=ldap;

  • Press after typing the set trace command.

  • Next, perform an search via eIAM and you will see an attempt by eIAM to connect to the router and search the AD namespace. The trace information will be stored in the "%DXHOME%\logs\iTechPoz-XYZ-Router_trace.log". What you are looking for are search operations that begin with:

    (Remote) -> #17 (SSL) [AD] DXLINK SEARCH-REQ

    This confirms that the remote connection with the Active Directory server is being conducted across an SSL encrypted link.

  • To reset the router trace back to it's default, type the following commands into the DSA's console window:

    dsa> set trace=none;
    dsa> logout;


  • You can verify that the data is being encrypted by using the Microsoft Network Monitor to sniff the network traffic between the CA Directory iTechPoz-Router DSA and the Active Directory server. Filter based upon port 636. An example of this network traffic can be seen in the illustration below (note the blue middle section).

Figure 7