IBM Tivoli Directory Server

 

Overview

You might want to configure WAS and WebSphere Portal access to your LDAP user registry over SSL to ensure the confidentiality of the data exchanged between WAS, WebSphere Portal, and your LDAP user registry. For example, user passwords are sent over the network between LDAP user registry and WebSphere Portal. This occurs to set the password if WebSphere Portal user management tools are used to create users and change passwords and also when WAS authenticates any user name and password pair through an LDAP BIND operation. Configuring LDAP over SSL can be important to protect sensitive data. Also, it might be required to ensure that user attributes that are retrieved from the directory are not viewed by someone watching packets on the network, if the attributes of a user include sensitive information or privacy is a concern.

In order to ensure that all this information remains private, it is necessary to configure both WAS and WebSphere Portal to use LDAP over SSL to the LDAP user registry. Configuring LDAP over SSL for WAS and WebSphere Portal is a separate operation from configuring the IBM HTTP Server to accept incoming browser requests over HTTPS or configuring HTTPS between the IBM HTTP Server and WAS in a distributed setup.

A full primer on the configuration of all the LDAP user registries and WAS is beyond the scope of this Portal Server documentation. Consult the documentation for your LDAP server to configure the user registry for SSL traffic. For IBM Tivoli Directory Server, see the most current documentation on IBM LDAP Implementation at...

www.ibm.com/software/webservers/appserv/was/support/

For WAS, see the IBM Redbook IBM WebSphere V5.0 Security, SG24-6573-00 is available, and Appendix B contains instructions for configuring WAS for LDAP over SSL. You can also consult the WAS product documentation.

Get LDAP (non-SSL) successfully working before setting up LDAP over SSL. This allows you to verify that the user registry is responding to LDAP requests before setting it up for SSL.

 

About keys and certificates

In general, the task of setting up WAS and WebSphere Portal to use LDAP over SSL to the LDAP user registry consists of bringing the necessary certificates into key storage files that WAS and WebSphere Portal will use. The necessary certificates mentioned are the signing certificates for the LDAP server certificate. The important point to note is that any certificates required to establish the full certificate signing trust chain must be made available to WAS and WebSphere Portal. For a self-signed certificate, the certificate trust chain consists of only the one self-signed LDAP server certificate. For a certificate signed by a CA, the certificate chain confirming the identity and validity of the signing CA must be included. Either a purchased certificate or a self-generated CA signing certificate can be used. Some configuration setting changes must also be made to tell WAS and WebSphere Portal that LDAP over SSL should be used. Usually, it is only necessary to bring a signing certificate from the LDAP server to the WAS and WebSphere Portal. This step allows the authentication of the server side of the SSL connection. WAS and WebSphere Portal are LDAP clients to the LDAP user registry server. The client side is authenticated by doing an LDAP BIND within the SSL connection. The identity used by WAS to perform this BIND is the Bind DN configured on the WAS Security Console. The identity used by WebSphere Portal to perform this BIND is the adminId configured in wp_root/wmm/wmm.xml.

In some cases, if the LDAP user registry is configured to require mutually authenticated SSL for the LDAP connection, meaning that it will request the client-side certificate, then signing certificates for WAS and WebSphere Portal must be moved to the LDAP Server key storage. In this case, WAS and WebSphere Portal will still do LDAP BINDs using the IDs and passwords configured, even though the SSL connection has already performed a mutual authentication.

 

Set up LDAP over SSL

It is required that you first get LDAP (non-SSL) successfully working before setting up LDAP over SSL. This allows you to verify that the user registry is responding to LDAP requests before setting it up for SSL.

However, WebSphere Portal also supports installing directly to an LDAP user registry over SSL, even thought it is not recommended.

  1. Install WebSphere Portal and WAS
  2. Install and setup your LDAP
  3. Generate or import certificates as necessary and activate SSL on the directory
  4. Import certificate(s) to cacerts to enable SSL connection
  5. Close down the non-SSL port of the LDAP user registry server (optional)

 

1. Install WebSphere Portal and WAS

Refer to Install WebSphere Portal for more information.

Also refer to Install WebSphere Portal for instructions on how to install WebSphere Portal on an existing instance of WAS that has security enabled.

 

2. Install and setup your LDAP

Get LDAP (non-SSL) successfully working before setting up LDAP over SSL. This allows you to verify that the directory is responding to LDAP requests before setting it up for SSL.

 

3. Generate or import certificates as necessary and activate SSL on the directory

It is possible for IBM Tivoli Directory Server to use either self-signed certificates or signing certificates signed by a CA (Certificate Authority) to enable LDAP over SSL.

IBM Tivoli Directory Server includes a security key management utility, such as gsk7ikm, which can be used to generate a self-signed certificate or to import purchased certificates into the IBM Tivoli Directory Server keystore. You should consult the IBM Tivoli Directory Server documentation for the details of how to import a CA certificate or create a self-signed certificate in a key database file and extract that certificate so that it can be moved to the WAS and WebSphere Portal. A brief overview of the steps to create a self-signed certificate are below:

  1. Activate the security key management utility. For example, gsk7ikm.

  2. Open an existing CMS Key Database file, if your directory server is already configured for SSL, or create a new CMS Key Database file. If you open an existing file, provide the password for that file. If you create a new file, you are asked to supply a password to secure access to that file. remember that password.

  3. Within that CMS Key Database file, create a new self-signed certificate, using X.509 V3 format and 1024-bit key size. Give the certificate a label. remember this label.

  4. Extract the new self-signed certificate as a certificate file using Base64-encoded ASCII data as the data type. This will save the certificate to a filename of your choice with an extension of .arm.

  5. If it is not already configured, set up IBM Tivoli Directory Server for LDAP over SSL using the CMS Key Database file containing the self-signed certificate. For details on this step, consult the IBM Tivoli Directory Server documentation.

 

4. Import certificate(s) to WebSphere Portal to enable SSL connection

 

Moving LDAP server certificates to WAS and WebSphere Portal

  1. Make the signing certificate from IBM Tivoli Directory Server (either the CA certificate or the self-signed certificate) available to the WAS and WebSphere Portal machine. This can be done by moving the file via a network transfer or removable media. Note that a CA certificate must be in Base64-encoded ASCII data format as a .arm file in order to be imported by the WAS key management utilities. The IBM Tivoli Directory Server key management utilities (gsk7ikm) can be used to format a CA certificate which is not in the right format.

 

Importing certificates to a WAS keystore

To make either the self-signed certificate or the CA certificate chain available to WAS and WebSphere Portal, use the key management tool supplied by WAS to import the certificate(s) into the necessary Java Key Store (.jks) format key storage files. Note that the WAS-supplied key management tool, IKeyMan, is not the same as the IBM Tivoli Directory Server key management tool, even though the user interface is very similar. IKeyMan supports the Java Key Store file formats necessary for WAS and WebSphere Portal, whereas the IBM Tivoli Directory Server key management tool does not. Consult the WAS documentation and the IBM Redbook cited above for details about how to use this tool.

A brief overview of the steps to import the certificates to configure LDAP over SSL for WAS is:

  1. Activate the IKeyMan utility, which is located in was_root/bin. One way to do this is to issue the ikeyman.exe or ikeyman.sh command from the command line, depending on your operating system.

  2. Open the Java Key Store file which will be used by WAS for LDAP over SSL. The user can create new key files and define a new SSL repertoire. WAS provides a default repertoire called DefaultSSLSetting. Use the default repertoire which contains the default WAS server trust file. Open DummyServerTrustFile.jks located at was_root/etc directory. The password to the dummy server trust file is "WebAS".

  3. Select Signer Certificates from the top pulldown, then click Add.

  4. Select Base64-encoded ASCII data as the data type, and browse to the certificate file of that type that you exported from the IBM Tivoli Directory Server.

  5. You will be asked for a label for the new certificate. Enter the same value that you specified for the label when you created the certificate.

  6. Save the updated key store file.

 

Importing certificates to a WebSphere Portal keystore

WebSphere Portal can be configured to use to a specifically-named Java Key Store so that WebSphere Portal and WAS can share the same configured truststore in the SSL configuration of the CSIv2 Outbound Transport. To specify the Java Key Store, follow these steps:

  1. Stop WebSphere Portal

  2. Logon to the WAS Administration Console.

  3. Navigate to Security > User Registries > LDAP.

  4. Check the sslEnabled box (set sslEnabled to true).

  5. Set the LDAP Port to 636.

  6. Save changes.

  7. Stop and restart your WAS (server1).

  8. In a text editor, open the file wmm.xml in the wp_root/wmm directory, where wp_root is the installation directory for WebSphere Portal.

  9. Navigate to the stanza that begins ldapRepository name="wmmLDAP".

  10. Verify that ldapPort="636".

  11. Verify that sslEnabled="true".

  12. At the end of this stanza, add sslTrustStore="was_root\etc\DummyServerTrustFile.jks", where was_root is the installation directory for WAS.

  13. Save the file.

  14. Stop and restart your WAS (server1).

  15. Restart WebSphere Portal.

 

5. Close down the non-SSL port of the LDAP directory server (optional)

This is an optional step. Closing the non-SSL port of the directory will ensure that traffic exchanged with the user registry by WAS, WebSphere Portal, or any other application, is confidential.

 

Next steps

You have completed this step. Continue to the next step by choosing the following topic:

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

Tivoli is a trademark of the IBM Corporation in the United States, other countries, or both.