Technote (FAQ)
Question
One option, when setting up the IBM Directory Server Web Administration Console, is to communicate with the Directory Server via an SSL secured connection. How can this be configured when the LDAP server is setup using SSL serverAuth?
Answer
STATEMENT OF INTENT
This document serves as a 'How to' example of setting up the IBM Tivoli Directory Server Web Administration Tool 6.0, which is installed on the WebSphere Application Server (WAS), to communicate via an SSL connection to an IBM Directory Server 6.0 configured for SSL using serverAuthentication.
For this example, the ITDS LDAP Server is installed and running on a Windows 2003 Server; however, this example will work the same for any ITDS supported operating system. Also, it is assumed that the LDAP server is already configured for SSL communication using server Authentication. Also, please install the latest patches and the latest version of the Web Administration Tool (See Related Information for link). The minimum required level of ITDS for this functionality is FixPack 2.
SETTING UP THE WEB ADMIN TOOL FOR SSL COMMUNICATION TO LDAP SERVER
Java-based applications such as the Web Administration Console require JKS key database types, whereas C-applications like the IBM Tivoli Directory Server require CMS key database types.
Therefore, the first step in setting up the Web Admin Tool is to create a JKS key database file.
To do this, the administrator must start the IBM Key Management Utility, also known as IKEYMAN (gsk7ikm.exe), and under the Key Database File tab, select 'New...'.
*NOTE* The IBM Key Management Utility might encounter issues running if the Environment Variables are not set properly. Please See Appendix O of the Install guide for LDAP 6. (See Related Information)
After selecting 'New..." from the menu, another window appears, which will allow the administrator to choose Key database type, File name, and location.
This is very similar to setting up the CMS Key database as the user did when originally configuring the ITDS ldap server for SSL communication. The difference is that instead of using a CMS keystore, the administrator is now using a JKS keystore which is the required keystore type for the Web Administration Tool.
Select a file name and also a location to store the file.
Select 'OK' to continue...
The next window allows the administrator to select the password of the JKS file just created.
Click 'OK' to complete the creation of the JKS file.
Since this example is demonstrating setting up the Web Administration tool to communicate with the ITDS ldap server using ssl server authentication there is no need to create a personal certificate. The next step in this procedure is to extract the SSL certificate from the CMS key database used by the ITDS ldap server and import it into the newly created JKS key database.
Again using the IBM Key Management tool, open up the CMS key database used by the ITDS ldap server.
Click “Key Database File” from the top tool bar as shown in the first illustration and then click “Open”.
In this example, the CMS key database is called “ldap_key.kdb” and it is store in the C:\certificates\ directory.
Select 'OK' to continue...
User will be prompted for the password to the ldap_key.kdb.
Type password to the KDB file and click 'OK'.
Once opened, user will notice that the Personal Certificates panel of the Key database content window is displayed. For this example, the Personal Certificate used is a self signed certificate labeled "LDAP_Cert".
The next step would be to extract the certificate into an arm file than can be imported into the newly created JKS file.
Select the LDAP_Cert certificate and click on the 'Extract Certificate...' button.
For the Data type, the Administrator can select either Base64-encoded ASCII data or Binary DER data, but what ever data type user selects, user will have to use the same when importing the certificate into the JKS key database. For this example Base64-encoded ASCII data type is used.
Verify that the Data Type is 'Base64-encoded ASCII data'; then enter the Certificate file name with the .arm extension and the location of where to extract the certificate to.
Click 'OK' to continue and extract the certificate.
Once this is completed, the administrator will need to reopen the JKS file created earlier via the IKEYMAN utility.
Click 'OK' when the JKS file is selected and enter password when prompted.
Once opened, user will notice that the 'Signer Certificates' are displayed by default. This is because no personal certificates are loaded or actually needed when setting up Server Authentication to the LDAP Server.
To add the extracted certificate just created from the LDAP's KDB file, click on the 'Add...' button to import the certificate.
Remember to keep the same 'Data type' as before, in this case 'Base64-encoded ASCII data' and then select the ldap_cert.arm file to add to the signer certificates of the JKS file.
Click 'OK' to continue.
User will now be asked for the Label to be used for the certificate. Use a name that can be easily determined.
*NOTE* The Certificate Label can not be the same as the actual certificate used in the LDAP Server Certificate.
Select 'OK' to complete addition operation.
Once completed successfully, the Signer Certificates will now show the new Certificate Label.
The IBM Key Management Utility can now be closed.
The next step is to access the Web Administration Console via a Web Browser and login to the Console Admin to finish Configuration.
*NOTE* By Default the Username is superadmin and Password is secret, unless changed.
Click 'Login'
Once logged in as Console Admin, access the 'Manage Console Severs', under the 'Console Administration' section on the left side of the screen.
In this example, the console is already configured to access the Directory Server via the non-ssl port of 389.
The goal is to have a secured connection from the Console to the LDAP server via port 636.
Select 'Add...' to continue the configuration.
Select the Hostname, the secured port which by default is 636 and the Administration port.
*NOTE* Each instance of the LDAP server has four unique ports, a non-ssl port, an ssl port, an administration port and a secure administration port. To see what these are configured as, the administrator can run the idsilist command from a command line or terminal window.
idsilist -a
*************************************************************************************************
Directory server instances:
--------------------------------------
Instance 1:
Name: db2admin
Version: 6.0
Location: C:
Description: IBM Tivoli Access Manager Instance
IP Addresses: All available
Port: 389
Secure Port: 636
Admin Daemon Port: 3538
Admin Daemon Secure Port: 3539
Type: Directory Server
*************************************************************************************************
Be sure to check the 'Enable SSL encryption' checkbox.
Select 'OK' to continue.
The next step is to configure the Console to point to the newly created JKS files.
Under the 'Console Administration' section on the left side of the screen, select 'Manage Console Properties' then 'SSL key database'.
Configure the 'Key database path and file name' and the 'Trust database path and file name' to the JKS file created earlier along with the password.
Verify the JKS as the 'Key database file type, then select 'OK' to continue.
The Tivoli Directory Server Web Administration Tool is now configured to connect securely to the LDAP server.
*NOTE* To load the new information stored in the Web Administration Tool, the WebSphere Application Server must be restarted.
VERIFICATION
Logout of the Console Admin and return to the Login page, user will now see an option to select the LDAP server using the secure port.
Select 'Login' to login with Username and Password provided.
Success!!
Related information
Appendix O - GSKIT Setup for IBM Directory Server 6.0
Setting up LDAP 6.0 to use SSL using serverAuth
ITDS Patch Downloads
IBM Tivoli Directory Server Support
Product Alias/Synonym
IDS LDAP ITDS