LDAP and SSL configuration example

Use this end to end example to help you to configure Lightweight Directory Access Protocol (LDAP) and secure socket layer (SSL) for Log Analysis.

The steps here are for exemplary purposes to help you to understand how to set up LDAP authentication with SSL. The exact steps required to set up your own implementation will differ.
Note: If your LDAP certificates have been renewed, then you will need to configure Log Analysis to use the new LDAP certificates. Only the following steps from this topic will be required:
  1. Add the related LDAP root certificate to the truststore. The name specified for alias must be different to the one that is currently in use.
  2. Import certificates from the LDAP keystore in Log Analysis.

Prerequisites

Ensure you meet the following prerequisites:
  • Ensure that the Java™ home variable is set to JAVA_HOME=/opt/IBM/LogAnalysis/ibm-java/jre. For example, to set this variable, enter the following command:
    export JAVA_HOME=/opt/IBM/LogAnalysis/ibm-java/jre

Configure the LDAP registry helper properties

Configure the properties of the LDAP registry helper script:
  1. Edit the <HOME>/IBM®/LogAnalysis/utilities/ldapRegistryHelper.properties file.
  2. Ensure that you do not change the default LDAP type property:
    ldap_type_property=IBM Tivoli Directory Server
  3. Specify the mandatory connection information:
    ldap_hostname_property=123.example.com
ldap_port_property=636
ldap_baseDN_property=o=example.com
  4. Specify the optional connection properties for the target LDAP server. The following properties are optional. The ldap_bindPassword_property parameter is later encrypted by the ldapRegistryHelper_config.xml script and the encrypted version is written to the ldapRegistry.xml file. The password is automatically removed from the ldapRegistryHelper.properties file after the ldapRegistryHelper_config.xml script runs. The following example includes some default values:
    ldap_bindDN_property=
ldap_bindPassword_property=
ldap_realm_property=LdapRegistryRealm
ldap_id_property=example
ldap_ignoreCase_property=true
  5. Specify the default LDAP filters for each vendor. The filter properties that are used by the ldapRegistryHelper_config.xml script. These properties are determined by the LDAP type that is specified in the ldap_type_property parameter in step 1.
    # IBM Tivoli Directory Server
ldap_TDS_userFilter_property=(&(emailAddress=%v)(objectclass=person)) 
ldap_TDS_groupFilter_property=(&(cn=%v)(|(objectclass=groupOfNames)
(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs))) 
ldap_TDS_userIdMap_property=*:emailAddress 
ldap_TDS_groupIdMap_property=*:cn 
ldap_TDS_groupMemberIdMap_property=ibm-allGroups:member;
ibm-allGroups:uniqueMember;groupOfNames:member;groupOfUniqueNames:
uniqueMember

Run the LDAP registry helper script

To run the LDAP registry helper script, enter the following command:
<HOME>/IBM/LogAnalysis/utilities/
ldapRegistryHelper.sh config
The script generates the ldapRegistry.xml based on the properties that are specified in the <HOME>/IBM/LogAnalysis/utilities/ldapRegistryHelper.properties file.

Edit the ldapRegistry.xml file

Next, you need to edit the <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/ldapRegistry.xml.
  1. Edit the <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/ldapRegistry.xml
  2. Add the following properties:
    sslEnabled="true"
sslRef="LDAPSSLSettings">
    For example:
    <server>
<ldapRegistry
host="123.example.com"
port="636"
baseDN="o=example.com"
realm="LdapRegistryRealm"
id="example"
ignoreCase="true"
ldapType="IBM Tivoli Directory Server"
sslEnabled="true"
sslRef="LDAPSSLSettings">
<idsFilters
userFilter="(&amp;(emailAddress=%v)(objectclass=person))"
groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
userIdMap="*:emailAddress"
groupIdMap="*:cn"
groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
groupOfNames:member;groupOfUniqueNames:uniqueMember"/>
</ldapRegistry>
</server>

Edit the unityConfig.xml file

Next, you need to add the Log Analysis user information to your LDAP configuration information in Log Analysis:
  1. Edit the <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/unityConfig.xml.
  2. Specify the following attributes:
    <server>
<application type="war" id="Unity" name="Unity"
location="${server.config.dir}/apps/Unity.war">
<application-bnd>
<security-role name="UnityUser">
<group name="UnityUsers" />
<group name="UnityAdmins" />
<group name="IGA_SCALA_ADMIN" />
<group name="IGA_SCALA_USER" />
</security-role>
<security-role name="UnityAdmin">
<group name="UnityAdmins" />
<group name="IGA_SCALA_ADMIN" />
</security-role>
</application-bnd>
</application>

<oauth-roles>
<authenticated>
<group name="UnityUsers" />
</authenticated>
</oauth-roles>
</server>
    Where IGA_SCALA_ADMIN and IGA_SCALA_USER are the LDAP groups. Change these group names if your users belong to different groups.

Create the JKS keystore

To create the JKS keystore file:
  1. Go to the <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity directory.
  2. Run the keytool. For example:
    unity@nc9042037056 Unity] /home/unity/LogAnalysis/ibm-java/jre/bin/keytool 
-genkeypair -alias scala -keyalg RSA -keystore LdapSSLKeyStore.jks 
-keysize <encryption-key-size> -validity 7300
Enter keystore password:
Keystore password is too short - must be at least 6 characters
Enter keystore password:
Keystore password is too short - must be at least 6 characters
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: <SCALA_SERVER_FQDN>
What is the name of your organizational unit?
[Unknown]: IGA
What is the name of your organization?
[Unknown]: IGA
What is the name of your City or Locality?
[Unknown]: US
What is the name of your State or Province?
[Unknown]: US
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=IGA, OU=IGA, O=IGA, L=US, ST=US, C=US correct? (type "yes" or "no")
[no]: yes

Enter key password for <scala>:
(RETURN if same as keystore password):

[unity@nc9042037056 Unity]$ /home/unity/IBM/LogAnalysis/ibm-java/jre/bin/
keytool -genkeypair -alias scala -keyalg RSA -keystore LdapSSLKeyStore.jks 
-keysize <encryption-key-size> -validity 7300
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: nc9042037056.tivlab.raleigh.ibm.com
What is the name of your organizational unit?
[Unknown]: IGA
What is the name of your organization?
[Unknown]: IGA
What is the name of your City or Locality?
[Unknown]: US
What is the name of your State or Province?
[Unknown]: US
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=nc9042037056.tivlab.raleigh.ibm.com, OU=IGA, O=IGA, L=US, ST=US, 
C=US correct? (type "yes" or "no")
[no]:
    Where <encryption-key-size> is the size of the encryption key; for example, 2048.

Create the JKS truststore

To create the JKS truststore:
  1. Go to the <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity directory.
  2. Run the keytool. For example:
    [unity@nc9042037056 Unity] /home/unity/LogAnalysis/ibm-java/jre/bin/
keytool -genkeypair -alias scala -keyalg RSA -keystore 
LdapSSLTrustStore.jks -keysize <encryption-key-size> -validity 7300
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: <SCALA_SERVER_FQDN>
What is the name of your organizational unit?
[Unknown]: IGA
What is the name of your organization?
[Unknown]: IGA
What is the name of your City or Locality?
[Unknown]: US
What is the name of your State or Province?
[Unknown]: US
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=IGA, OU=IGA, O=IGA, L=US, ST=US, C=US correct? 
(type "yes" or "no")
[no]: yes

Enter key password for <scala>:
(RETURN if same as keystore password):
    Where <encryption-key-size> is the size of the encryption key; for example, 2048.

Add the related LDAP root certificate to the truststore

To add the root certificate to the truststore, run the keytool:
[unity@nc9042037056 Unity] /home/unity/LogAnalysis/ibm-java/jre/bin/keytool 
-import -trustcacerts -alias root -file bluepages.crt 
-keystore LdapSSLTrustStore.jks
Enter keystore password:
Certificate already exists in system-wide CA keystore 
under alias <equifaxsecureca>
Do you still want to add it to your own keystore? 
[no]: yes
Certificate was added to keystore

Encode the trust and keystore passwords

  1. Go to the <HOME>/IBM/LogAnalysis/wlp/bin/.
  2. Run the security utility tool. For example, the password that is used here, t1v011, is the same as the one used to create the trust and keystores in the previous step:
    [unity@nc9042037056 bin]$ ./securityUtility encode t1v0l1
{xor}K24pbzNu

Edit the server.xml file

To add the trust and keystore details to the server.xml file:
  1. Go to the <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity directory.
  2. Edit the server.xml file.
  3. Add the security settings before the defaultKeystore tag. For example:
    <ssl id="LDAPSSLSettings" keyStoreRef="LDAPKeyStore" 
trustStoreRef="LDAPTrustStore" />

<keyStore id="LDAPKeyStore" location=
"${server.config.dir}/LdapSSLKeyStore.jks"
type="JKS" password="{xor}K24pbzNu" />
<keyStore id="LDAPTrustStore" location=
"${server.config.dir}/LdapSSLTrustStore.jks"
type= "JKS" password="{xor}K24pbzNu" />


<!-- default keystore for certificates. located in 
<install home>/wlp/usr/servers/Unity/resources/security -->
<!-- file name is key.jks . If it does not exist at startup 
it will be automatically created. -->
<keyStore id="defaultKeyStore" 
password="{xor}MzA4PjE+MyYrNjws" />

Enable the LDAP configuration

To enable the LDAP configuration, go to the <HOME>/IBM/LogAnalysis/utilities directory and run the following command: 
ldapRegistryHelper.sh enable

Import certificates from the LDAP keystore in Log Analysis

Finally, you need to import certificates from the LDAP keystore in Log Analysis
  1. Export the certificate from LdapSSLKeyStore.jks.
    <HOME>/IBM/LogAnalysis/ibm-java/bin/keytool -exportcert -keystore <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/LdapSSLKeyStore.jks -alias scala -file <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/ldap-clientcert.crt
  2. Import the ldap-clientcert.crt certificate file:
    <HOME>/IBM/LogAnalysis/ibm-java/bin/keytool -import -file <HOME>/IBM/LogAnalysis/wlp/usr/servers/Unity/ldap-clientcert.crt -keystore ../jre/lib/security/cacerts -alias scala