WebSphere

 

Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows

 

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

 

Overview

You might want to configure IBM® WebSphere® Application Server and WebSphere Portal Express access to your LDAP user registry over SSL to ensure the confidentiality of the data exchanged between WebSphere Application Server, WebSphere Portal Express, and Domino Directory.

For example, user passwords are sent over the network between the LDAP user registry and WebSphere Portal Express. This occurs to set the password if WebSphere Portal Express 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, configure both WAS and WebSphere Portal Express to use LDAP over SSL to the LDAP user registry. Configuring LDAP over SSL for WAS and WebSphere Portal Express 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 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 WebSphere Portal Express documentation. Consult the documentation for your LDAP server to configure the directory for SSL traffic. For WAS, refer to IBM Redbooks and search for "Security Handbooks" for the latest information about configuring WAS for LDAP over SSL.

You can also consult the WAS library.

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 WAS and WebSphere Portal Express 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 WAS and WebSphere Portal Express. 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 WAS Java Key Store (.jks) for WAS LDAP over SSL and into the cacerts file for WebSphere Portal Express 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 WAS Java Key Store (.jks) for WAS LDAP over SSL and into the cacerts file for WebSphere Portal Express usage.

The WAS and WebSphere Portal Express 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 WAS 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 WAS and the default JSSE key stores using the WAS key management tool. To import the file, follow the procedures outlined here.

In general, the task of setting up WAS and WebSphere Portal Express 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 Express 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 WAS and WebSphere Portal Express that LDAP over SSL should be used. Usually, you only need to bring a signing certificate from the LDAP server to WAS and WebSphere Portal Express. This step allows the authentication of the server side of the SSL connection. WAS and WebSphere Portal Express 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 Express to perform this BIND is the adminId.

For Windows and Linux 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 WAS and WebSphere Portal Express must be moved to the LDAP

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

    Also refer to Installing on Windows and Linux for instructions on how to install WebSphere Portal Express on an existing WAS profile that has security enabled.

  2. Install and set up your LDAP

    IBM recommends that you first 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

    For 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 WAS and WebSphere Portal Express.

    Optionally, you can use the IBM System i5 Digital Certificate Manager. See the Digital Certificate Manager topic in the System i5 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 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.

      You must remember that password.

    3. Within that CMS Key Database file, create a new self-signed certificate, using X.509 Version 3 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 your 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.

    For Windows and Linux 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 WAS and WebSphere Portal Express. 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 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.

      You must remember that password.

    3. Within that CMS Key Database file, create a new self-signed certificate, using X.509 Version 3 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 your 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, you 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 your 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.

    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 your browser documentation on certificates for detailed instructions on importing and exporting them.

      1. Access...

        https://dominowebserver

      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.

  4. Import certificates to WebSphere Portal Express to enable SSL connection

    • Moving LDAP server certificates to WAS and WebSphere Portal Express

      Make the signing certificate from Domino Directory (either the CA certificate or the self-signed certificate) available to the WAS and WebSphere Portal Express machine. You 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 WAS 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.

    • Importing certificates to a WAS keystore

      i5/OS:

      If your application uses commercial certificate authority certificates (signer or CA certificates), you might be able to use the cacerts keystore (the default trust keystore) with your 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 your private copy of the cacerts file. Also, note that initially, all keystores created using iKeyman contain a number of commercial CA certificates.

      You can create your Java keystores in any i5/OS integrated file system directory. However, it might be convenient to place them in the same directory as those that are used by your WebSphere Portal Express installation..

      This might make it easier to include them in your backup and restore procedure. WAS provides an initial set of Java keystores that are used to secure connections between WebSphere Portal Express components.

      These keystores are found in the etc directory of your WebSphere Portal Express installation.

      For example, the keystores for the default profile are found in the app_server_root/etc directory.

      For an example of how to create a Java keystore, see Using Java keystore files in the WAS for System i5 information center.

      Linux and Windows:

      To make either the self-signed certificate or the CA certificate chain available to WAS and WebSphere Portal Express, use the key management tool supplied by WAS to import the certificates into the necessary Java Key Store (.jks) format key storage files. Note that the key management tool supplied by WAS is IKeyMan.

      IKeyMan supports the Java Key Store file formats necessary for WAS and WebSphere Portal Express. Consult the WAS 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 WAS follow:

      1. Activate the IKeyMan utility, which is located in...

        was_profile_root/bin

        You can activate this utility by issuing 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_profile_root/etc

        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.

  5. Import certificates to a WebSphere Portal Express keystore

    i5/OS:

    You must also import the certificates to a keystore that can be used by the WebSphere Portal Express. In this case, WebSphere Portal Express 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 Express can be configured to use to a specifically-named Java Key Store so that WebSphere Portal Express 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 Express.

    2. Logon to the WAS 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_number.

    6. Save changes.

    7. Perform the following steps to stop and restart the WAS:

      1. Open a command prompt and change to the following directory:

      2. Enter the following command:

        • Linux:

          ./stopServer.sh server1 -user admin_userid -password admin_password

        • Windows:

          stopServer.bat server1 -user admin_userid -password admin_password

        • i5/OS:

          stopServer.sh server1 -profileName wp_profile -user admin_userid -password admin_password

      3. Enter the following command:

        • Linux:

          ./startServer.sh server1

        • Windows:

          startServer.bat server1

        • i5/OS:

          startServer.sh server1 -profileName wp_profile

    8. In a text editor, open the file wmm.xml located in the portal_server_root/wmm directory.

      In a clustered environment, the wmm.xml file is moved from the portal_server_root/wmm/ directory to the was_profile_root/config/wmm directory via a configuration task that uploads and replicates to all cluster nodes.

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

    10. Verify that ldapPort="port_number".

    11. Verify that sslEnabled="true".

    12. At the end of this stanza, update

      The full pathname is only mandatory if the sslTrustStore file is not under was_profile_root\etc\; otherwise, you can just use the file name.

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

      In this case, you will need to import the root CA certificate for your LDAP server into the cacerts

    13. As part of setting up SSL for the LDAP repository in a cluster environment, any changes made within the deployment manager to the file defined by sslTrustStore and changes made to the cacerts file are not automatically replicated to all nodes in the cell and must be manually backed up and copied to the node agents. The location of the dummy keys on the deployment manager is...

      was_profile_root\dmgrname\etc\

    14. Save the file.

    15. Perform the following steps to stop and restart the WAS:

      1. Open a command prompt and change to the following directory:

      2. Enter the following command:

        • Linux:

          ./stopServer.sh server1 -user admin_userid -password admin_password

        • Windows:

          stopServer.bat server1 -user admin_userid -password admin_password

        • i5/OS:

          stopServer.sh server1 -profileName wp_profile -user admin_userid -password admin_password

      3. Enter the following command:

        • Linux:

          ./startServer.sh server1

        • Windows:

          startServer.bat server1

        • i5/OS:

          startServer.sh server1 -profileName wp_profile

    16. Perform the following steps to stop and restart the WebSphere Portal Express server:

      1. Open a command prompt and change to the following directory:

      2. Enter the following command:

        • Linux:

          ./stopServer.sh WebSphere_Portal -user admin_userid -password admin_password

        • Windows:

          stopServer.bat WebSphere_Portal -user admin_userid -password admin_password

        • i5/OS:

          stopServer.sh WebSphere_Portal -profileName wp_profile -user admin_userid -password admin_password

      3. Enter the following command:

        • Linux:

          ./startServer.sh WebSphere_Portal

        • Windows:

          startServer.bat WebSphere_Portal

        • i5/OS:

          startServer.sh WebSphere_Portal -profileName wp_profile

  6. 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 WAS, WebSphere Portal Express, or any other application, is confidential.

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

 

Parent topic:

Domino Directory

 

Previous topic:

Verify LDAP

 

Related tasks

Enable SSL connections to a Domino server