Set up LDAP over SSL with Domino Directory

 

+

Search Tips   |   Advanced Search

 

1. Overview
2. About keys and certificates
3. Set up LDAP over SSL
   • Install WebSphere Portal and WAS
   • Install and set up the LDAP
   • Generate or import certificates as necessary and activate SSL on the directory
   • Import certificates to WebSphere Portal to enable SSL connection
   • Close down the non-SSL port of the LDAP user registry server (optional)

 

Overview

We can configure IBM WebSphere Application Server and WebSphere Portal access to the LDAP user registry over SSL to ensure the confidentiality of the data exchanged between WebSphere Application Server, WebSphere Portal, and Domino Directory.

For example, user passwords are sent over the network between the 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 WebSphere Application Server 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.

To ensure that all this information remains private, configure both WebSphere Application Server and WebSphere Portal to use LDAP over SSL to the LDAP user registry. Configuring LDAP over SSL for WebSphere Application Server and WebSphere Portal with or without realm support is a separate operation from configuring the HTTP Server to accept incoming browser requests over HTTPS, or configuring HTTPS between the HTTP Server and WebSphere Application Server in a distributed setup.

A full primer on the configuration of all the LDAP user registries and WebSphere Application Server is beyond the scope of this WebSphere Portal documentation. Consult the documentation for the LDAP server to configure the directory for SSL traffic. For WebSphere Application Server, refer to redbooks.ibm.com and do a search for Security Handbook for the latest information about configuring WebSphere Application Server for LDAP over SSL.

IBM recommends that you first get LDAP (non-SSL) 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.

 

About keys and certificates

Configuring LDAP over SSL from WebSphere Application Server and WebSphere Portal to Lotus Domino as the LDAP user registry is almost the same as for IBM Directory Server or any of the other LDAP user registry servers. Lotus Domino will present a signed certificate as part of the LDAP-over-SSL handshake. The signer certificates for this Domino Directory server certificate must be available to WebSphere Application Server and WebSphere Portal. If the Domino Directory server certificate is self-signed, then that same self-signed certificate must be imported as a signer certificate into the named WebSphere Application Server Java Key Store (.jks) for WebSphere Application Server LDAP over SSL and into the cacerts file for WebSphere Portal usage. If the Domino Directory server certificate is signed by a CA certificate chain, then that CA certificate chain must be imported as signer certificates into the named WebSphere Application Server Java Key Store (.jks) for WebSphere Application Server LDAP over SSL and into the cacerts file for WebSphere Portal usage. The WebSphere Application Server and WebSphere Portal configuration steps are then identical to that for any other directory.

However, there are some slight differences in the Lotus Domino key management utilities; they generate key files that are compatible with the GSKIT key management tool, provided with HTTP Server, but not directly with the WebSphere Application Server key management tool. So, if Lotus Domino key management has been used to generate self-signed certificates, then the GSKIT key management tool must be used as an intermediate step to extract that certificate in Base64-encoded ASCII format (the.arm file) which can then be imported to WebSphere Application Server and the default JSSE key stores using the WebSphere Application Server key management tool. To import the file, follow the procedures outlined here.

In general, the task of setting up WebSphere Application Server and WebSphere Portal to use LDAP over SSL to the LDAP user registry consists of bringing the necessary certificates into key storage files that WebSphere Application Server and WebSphere Portal will use. The necessary certificates mentioned are the signing certificates for the LDAP server certificate. Some configuration setting changes must also be made to tell WebSphere Application Server and WebSphere Portal that LDAP over SSL should be used. Usually, you only need to bring a signing certificate from the LDAP server to WebSphere Application Server and WebSphere Portal. This step allows the authentication of the server side of the SSL connection. WebSphere Application Server 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 WebSphere Application Server to perform this BIND is the Bind DN configured on the WebSphere Application Server Security Console. The identity used by WebSphere Portal to perform this BIND is the adminId. For Windows and UNIX, this ID is configured in...

portal_server_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 WebSphere Application Server and WebSphere Portal must be moved to the LDAP Server key storage. The mechanisms for importing these certificates on the various LDAP servers are vendor-specific. Consult the directory documentation for specific instructions. Even in this case, WebSphere Application Server 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

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

 

Install WebSphere Portal and WebSphere Application Server

Refer to Installing on Windows and UNIX for more information.

Also refer to Installing on Windows and UNIX for instructions on how to install WebSphere Portal on an existing WebSphere Application Server profile that has security enabled.

 

Install and set up the LDAP

Refer to the two previous topics for more information:

• Installing LDAP

• Setting up LDAP

 

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

i5/OS :

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

IBM HTTP Server includes a security key management utility, such as ikeyman, which can be used to generate a self-signed certificate or to import purchased certificates into the Domino Directory keystore. You should consult the Domino Directory and ikeyman 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 WebSphere Application Server and WebSphere Portal.

Optionally, we can use the iSeries Digital Certificate Manager. See the Digital Certificate Manager topic in the iSeries information center for more information. A brief overview of the steps to create a self-signed certificate are below:

1. Activate the security key management utility, for example, ikeyman.

2. Open an existing CMS Key Database file, if the 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. You must 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. You must 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 the choice with an extension of.arm.

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

Windows and UNIX:

It is possible for Domino Directory to use either self-signed certificates or signing certificates signed by a CA (Certificate Authority) to enable LDAP over SSL. HTTP Server includes a security key management utility, such as ikeyman, which can be used to generate a self-signed certificate or to import purchased certificates into the Domino Directory keystore. You should consult the Domino Directory and ikeyman documentation for the details on 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 WebSphere Application Server and WebSphere Portal. A brief overview of the steps to create a self-signed certificate follows:

1. Activate the security key management utility, for example, ikeyman.

2. Open an existing CMS Key Database file, if the 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. You must 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. You must 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 file name of the choice with an extension of.arm.

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

Alternately, we can follow these steps to use the Domino Web server directly to create a self-signed certificate:

1. Enable Domino Web server.

2. Open the Server Certificate Admin application database called CERTSRV.NSF in Domino Web server.

3. Select the Create Key Ring with Self-Certified Certificate link in the Server Certificate Admin application database.

4. Type the following information to generate a self-certified certificate:
   • Key Ring File Name (an example is selfcert.kyr)

   • Key Ring Password (an example is password)

   • Common Name (an example is www.yourco.com, where yourco is the host.name of the Domino Web server)

   • Organization (an example is ibmportal)

   • State or Province (an example is NC)

   • Country (an example is US)

   Two files, named selfcert.kyr and selfcert.sth, will be generated.

5. Set up Domino Directory for LDAP and Domino Web server over SSL using this generated self-signed certificate. For details on this step, consult the Domino Directory documentation.

6. Make sure Domino Web server is started by completing the following steps:

   The steps explain how to work with the certificates using the Internet Explorer browser. If you use another browser, refer to the browser documentation on certificates for detailed instructions on importing and exporting them.

   1. Access https://Domino hostname whereDomino hostname is the host.name of the Domino Web server.

   2. Select View certificate on the Certificate Alert Window that pops up.

   3. Choose the Detail tab and export the.CER file by selecting the Copy to file button.

   4. Select Base-64 encoded X.509, which is the.CER format, in the export wizard.

   5. Save the certificate as a.CER file such as ldap.domino.cer.

 

Import certificates to WebSphere Portal to enable SSL connection

Moving LDAP server certificates to WebSphere Application Server and WebSphere Portal

Make the signing certificate from Domino Directory (either the CA certificate or the self-signed certificate) available to the WebSphere Application Server and WebSphere Portal machine. We can do this by moving the file through 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 WebSphere Application Server key management utilities. The HTTP Server key management utilities (ikeyman) can be used to format a CA certificate that is not in the right format.

 

Import certificates to a WebSphere Application Server keystore

i5/OS:

If the application uses commercial certificate authority certificates (signer or CA certificates), you might be able to use the cacerts keystore (the default trust keystore) with the application. The integrated file system path for cacerts is...

/QIBM/ProdData/Java400/jdk14/lib/security/cacerts

However, in no case should you attempt to modify the cacerts keystore. Rather, you should create a private copy of the cacerts file, and then add or remove certificates. The password for cacerts is changeit. Be sure to change the password that protects the private copy of the cacerts file. Also, note that initially, all keystores created using iKeyman contain a number of commercial CA certificates.

We can create the Java keystores in any iSeries integrated file system directory. However, it might be convenient to place them in the same directory as those that are used by the WebSphere Portal installation.. This might make it easier to include them in the backup and restore procedure. WebSphere Application Server provides an initial set of Java keystores that are used to secure connections between WebSphere Portal components. These keystores are found in the etc directory of the WebSphere Portal installation. For example, the keystores for the default profile are found in the directory...

app_server_root/etc

For an example of how to create a Java keystore, see Using Java keystore files in the WebSphere Application Server for iSeries information center. Unix and

Windows:

To make either the self-signed certificate or the CA certificate chain available to WebSphere Application Server and WebSphere Portal, use the key management tool supplied by WebSphere Application Server to import the certificates into the necessary Java Key Store (.jks) format key storage files. Note that the key management tool supplied by WebSphere Application Server is ikeyman. ikeyman supports the Java Key Store file formats necessary for WebSphere Application Server and WebSphere Portal. Consult the WebSphere Application Server documentation, including the IBM Redbook cited in this document, for details about how to use this tool. A brief overview of the steps to create a self-signed certificate and import the certificate to configure LDAP over SSL for WebSphere Application Server follow:

1. Activate the ikeyman utility, which is located in was_profile_root/bin. We can activate this utility by issuing the ikeyman.exe or ikeyman.sh command from the command line, depending on the operating system.

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

3. Select Signer Certificates from the top pull-down, 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 certificate file you just generated.

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 updates key store file.

 

Import certificates to a WebSphere Portal keystore

i5/OS:

You must also import the certificates to a keystore that can be used by the WebSphere Portal. In this case, WebSphere Portal has no configuration setting to point to a specifically named Java Key Store file. Instead, import the certificates into the default keystore file of the JVM, cacerts. However, in no case should you attempt to modify the cacerts keystore. Rather, you should create a private copy of the cacerts file, and then add or remove certificates. The configured truststore in the SSL configuration of the CSIv2 Outbound Transport must also be updated. WebSphere Portal can be configured to use to a specifically-named Java Key Store so that WebSphere Portal and WebSphere Application Server can share the same configured truststore in the SSL configuration of the CSIv2 Outbound Transport. To specify the Java Key Store...

1. Stop WebSphere Portal.

2. Logon to the WebSphere Application Server Administration Console.

3. Navigate to Security > Global Security> LDAP.

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

5. Set the LDAP Port to port.

6. Save changes.

7. Stop and restart the WebSphere Application Server (server1).

8. Edit wmm.xml in the portal_server_root/wmm directory, where portal_server_root is the installation directory for WebSphere Portal.

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

10. Verify that ldapPort="port".

11. Verify that sslEnabled="true".

12. At the end of this stanza, update

    • UNIX:

      sslTrustStore="was_profile_root/etc/DummyServerTrustFile.jks"

    • Windows:

      sslTrustStore="was_profile_root\etc\DummyServerTrustFile.jks"

    where was_profile_root is the profile directory of the WebSphere Application Server installation.

    Use the full pathname if the sslTrustStore file is not under was_profile_root \etc\.

    If you do not specify an sslTrustStore parameter here, Member Manager will use

    • UNIX:

      app_server_root/java/jre/lib/security/cacerts.jks

    • Windows:

      app_server_root\java\jre\lib\security\cacerts.jks

    In this case, import the root CA certificate for your LDAP server into the cacerts; see the Generate or import certificates as necessary and activate SSL on the directory step above for instructions.

13. Save the file.

14. Stop and restart the WebSphere Application Server (server1).

15. Restart WebSphere Portal.

 

Close down the non-SSL port of the LDAP user registry server (optional)

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

You must perform several additional configuration steps to enable SSL for uses other than LDAP, if WebSphere Portal components related to Collaborative Components are used.

 

Parent topic:

Set up LDAP over SSL

 

Related tasks

Enable SSL connections to a Domino server

 

---