Configuring Liberty Profile with LDAP

Authors: MikeDelargy
Build basis: CLM Versions 6.0.x

Below are steps to be used as a guideline to configure a CLM Deployment using Liberty Profile and LDAP. Keep in mind that LDAP registries are very flexible and guidance from your LDAP administrators / Network admins may be necessary to complete the configuration.

• We have included some examples from different types of LDAP environments that may offer you assistance.
• There are two parts to configuring the LDAP for Liberty Profile. Part 1 is configured during the JTS setup. Part 2 is configured outside of the JTS setup but immediately after Part 1.

CLM Installation and JTS setup.

This article is not designed to be The CLM Installation Guide nor is it a Guide to help you with the JTS SETUP. Rather, we introduce those topics to get you to the point of the LDAP configuration for Liberty Profile in your CLM Deployment.

Install CLM

When you install CLM, be sure to include the option to install with WebSphere Application Server, Liberty Profile.

• You do not need to select the option to include "Install application War files". These are needed when you are using a full install of WebSphere instead of Liberty Profile.
  

Install certificates if using ldaps (optional)

If you are planning to use LDAPS and have signer certificates to import, you must run ikeyman available in the Liberty install to import the certificate prior to running JTS Setup.

• Stop the CLM server
• Run ikeyman located in \server\jre\bin
• Select the open folder icon to Open a key database file dialog. Select JCEKS for key database type, then open the File browse option to select the certificate to import to Liberty. Enter a password for the certificate if prompted.
• Once the certificate displays in ikeyman, import it.
• Exit ikeyman and restart the CLM server.

NOTE: if you use the ibm-team-ssl.keystore provided by default, the password is ibm-team

This should allow you to make a secure ldap connection to your LDAP server with a signer certificate.

How do I need to configure third party certificate ( CA certificates) for WebSphere Application Server Liberty Profile?

Run JTS Setup

After you Install CLM and have your databases prepared, run the JTS Setup (JTS Setup is for a fresh installation, not an upgrade)

• Open a Browser
• Enter https://< your server name >:9443/jts/setup
• Set the Public URI, Accept the confirmation, click Test, and then Next.
  
• (You may get a warning depending on whether or not you are using a fully qualified server name.)
• Enter the database information for your JTS server and click the Create Tables button. When the tables are created, click Next.
• Next, optionally enable the default email or keep it disabled and click Next.
• Give the tool some time and when the applications that you have installed appear, click Register Applications. When the registration completes, click Next.
• It is now time to start the LDAP Configuration.
  
  

The LDAP Configuration for Liberty Profile

The LDAP Configuration for Liberty Profile is broken down into two steps. Step one is to configure JTS for the LDAP server and Step 2 is to configure Liberty Profile for the LDAP server.

LDAP Configuration Part 1

Select LDAP


Carefully enter the data you have received from your Network / LDAP Admin. Here is an example of a deployment

• LDAP Registry Location: ldap://jazzapacheds:389
• User Name: uid-wasadmin, ou=Users, dc=upgrade, dc=ws
• password: wasadmin
• Base User DN: ou=Users, dc=upgrade, dc=ws
• User Property Names Mapping: userID=uid,name=sn,emailAddress=mail
• Base group DN: ou=Groups, dc=upgrade, dc=ws
• Jazz to LDAP Groups: (default)
• Group Name Property: cn
• Group Member Property: uniquemember

Test the Connections. If your data is accurate, you would expect to see something like this:

You may be prompted to verify the LDAP user.
(Verification is needed if you have entered an LDAP user above and have not verified in earlier attempts.)


When the Test is positive, Save the LDAP Config Files.


NOTE: If you receive an error 'Failed to update LDAP Configuration Files', make sure you are using the ldapUserRegistry.xml file that came with the Liberty setup. Do not use any file that has been modified manually with LDAP settings.


You will receive a message on what to do next. (More details are included in Part 2 of this guide.)

Clicking Show Details will show the path to the server.xlm file.

You can enable the licenses that correspond to your applications at this time. If you do not do it at this time, you must do it prior to trying to create any projects.

When finished, Click Next.
(This is very important, clicking Next at this stage saves your LDAP information into the teamserver.properties file. You must do this prior to moving forward. If you do not click next, then you will need to re-enter the information when you return to complete the JTS / SETUP.)

• After the LDAP information is saved, log out of the JTS setup, Stop the JTS server, and proceed with Part 2 of the LDAP configuration.
  
• You will return to complete the JTS setup after you complete the LDAP configuration.

LDAP Configuration Part 2

In this part of the configuration, you will be working with the server.xml file, ldapUserRegistry.xml file, and the application.xml.

• The server.xml file is located here: < JazzTeamServer Installation Directory >\server\liberty\servers\clm\server.xml
• The ldapUserRegistry.xml file is located here: \server\liberty\servers\clm\conf\ldapUserRegistry.xml
  
• the application.xml file is located here: \server\liberty\servers\clm\conf\application.xml
  

(Suggestion: Make a backup copy of both the server.xml file and the ldapUserRegistry.xml file prior to making changes.)
Initially, Liberty Profile is configured to talk to an internal User Repository.
This is indicated in the server.xml file of Liberty Profile in this line:

<include location="conf/basicUserRegistry.xml"/> <br />

We need to tell Liberty Profile to point to the LDAP server to get information.

• In the server.xml file comment out the line for the basicUserRegistry and uncomment out the line for the ldapUserRegistery.
  
  

Configure the LDAP User Registry. As noted above, LDAP registries are very flexible and guidance from your LDAP administrators / Network admins may be necessary to complete the configuration.

Typical information needed from your LDAP Admin

• LDAP Server Name
• LDAP Server Port
• The User Filter
• The Group Filter
• Group Member ID
• User ID
• The Base DN
• bindDN
• bindPassword

Examples:

• LDAP Server Name -- > host="my.ldap.host"
• LDAP Server Port -- > port="389"
• The User Filter -- > userFilter="(&(uid=%v)(objectclass=inetOrgPerson))" (Sometimes there is more then one object class)
• The Group Filter --> groupFilter="(&(cn=%v)(objectclass=groupOfUniqueNames))"
• Group Member ID --> groupMemberIdMap="groupOfUniqueNames:uniquemember"
• User ID -- > userIdMap="*:uid"
• The Base DN -- > baseDN="dc=upgrade,dc=ws"
• bindDN -- > bindDN="cn=adminws,cn=Users,DC=clm,DC=admin,DC=ws" (There can be no spaces after the commas in the string!)
• bindPassword --> bindPassword="adminws"

The user filter is passed to the ldap server to get the members of the 'OU' (Organizational Unit).
The Group Filter is passed to the ldap server to get the groups in the 'OU'.
The Group Member ID is needed to identify how the user names are listed in the groups.
The User ID is what the LDAP server uses to identify the users.
The Base DN (Base Distinguished Names) is used by the LDAP server to describe the contents of the attributes of the Organizational unit
The bindDN is the user name configured for LDAP authentication. The bindDN is an administrator ldap name and it must have privileges to search the directory.
(Not all LDAP servers require a bindDN.)
The bindPassword is the password for the user listed in the bindDN

EXAMPLES.

We have included examples from multiple different LDAP environments to help guide you in your efforts.
For more information on configuring Liberty Profile for LDAP: Configuring LDAP User Registries In Liberty

APACHEDS

Apacheds is LDAP type "Custom". Therefore we have to use "Custom Filters" to communicate with the LDAP Server.

      <!-- Sample LDAP user registry configuration   -->
        <ldapRegistry 
        id="jazzapacheds" realm="jazzapacheds" ignoreCase="true" 
        host="jazzapacheds" port="10389" 
   recursiveSearch="true" 
        baseDN="dc=upgrade,dc=ws"
        ldapType="Custom" >

    <customFilters 
groupFilter="(&amp;(cn=%v)(objectclass=groupOfUniqueNames))" 
userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))" 
groupIdMap="*:cn" 
groupMemberIdMap="groupOfUniqueNames:uniquemember" 
userIdMap="*:uid"/> 
    </ldapRegistry>

Microsoft Active Directory

<featureManager> 
      <feature>ldapRegistry-3.0</feature>
</featureManager>

    <!-- Sample LDAP user registry configuration -->

   <ldapRegistry 

   id="MY_LDAP" 
   host="clm.admin.ws" 
   port="389" 
   baseDN="DC=clm,DC=admin,DC=ws" 
   ldapType="Microsoft Active Directory" 
   realm="clm.admin.ws" 
   bindDN="cn=adminws,cn=Users,DC=clm,DC=admin,DC=ws" 
   bindPassword="adminws" 
   ignoreCase="true" 
   recursiveSearch="true" 
   reuseConnection="true" 
   searchTimeout="120s">
      
   <activedFilters 
    userFilter="(&amp;(sAMAccountName=%v)(objectcategory=user))" 
   groupFilter="(&amp;(cn=%v)(objectcategory=group))" 
   userIdMap="user:sAMAccountName" 
   groupIdMap="*:cn" 
   groupMemberIdMap="*:member"/>
   
</ldapRegistry>

</server>

Tivoli Active Directory

    <ldapRegistry 
        id="CLMFVT_ldap" realm="SampleLdapIDSRealm" ignoreCase="true" 
        host="my.ldap.host" port="389" 
        baseDN="o=jke.ibm.com" 
        ldapType="IBM Tivoli Directory Server">  
        <idsFilters 
            userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))" 
            groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))" 
            userIdMap="*:uid" 
            groupIdMap="*:cn" 
            groupMemberIdMap="jke.ibm.com-allGroups:member;jke.ibm.com;AllGroups:uniqueMember;groupOfNames:member;groupOfUniqueNames:uniqueMember"> 

        </idsFilters> 
    </ldapRegistry> 

Novell Active Directory

Novell Active Directory is LDAP type "Custom". Therefore, we have to use "Custom Filters" to communicate with the LDAP Server.

<!-- Sample LDAP user registry configuration  -->

     <ldapRegistry baseDN="dc=rtp,dc=raleigh,dc=ibm,dc=com" 
       bindDN="cn=Administrator,dc=rtp,dc=raleigh,dc=ibm,dc=com" 
       bindPassword="TIohghr4wif1tHtlvxqKMfallAuj8Duc9EyvQO0bBtaYOjsZ2g==" 
     host=" mynovellserver.rtp.raleigh.ibm.com"  
      ignoreCase="false" 
      ldapType="Custom" port="389" 
      realm="mynovellserver.rtp.raleigh.ibm.com:389" 
     recursiveSearch="true" 
     sslEnabled="false">  

    <customFilters 
   groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=posixGroup)))" 
   groupIdMap="*:cn" 
   groupMemberIdMap="groupOfNames:member;ibm-allGroups:uniqueMember" 
   userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))" 
   userIdMap="*:uid">
    </customFilters>
    </ldapRegistry>

LDAP Custom Groups

You must now modify your application.xml file with the group memberships similar to the group mappings in the JTS Setup (LDAP Part 1). Your current application.xml file will have entries like this:

    
    <application type="war" id="jts" name="jts" location="${server.config.dir}/apps/jts.war">
        <application-bnd>
            <security-role name="JazzAdmins">
                <group name="JazzAdmins" />
            </security-role>
            <security-role name="JazzProjectAdmins">
                <group name="JazzProjectAdmins" />
            </security-role>
            <security-role name="JazzUsers">
                <group name="JazzUsers" />
            </security-role>
            <security-role name="JazzGuests">
                <group name="JazzGuests" />
            </security-role>
        </application-bnd>
    </application>

Change each of the application sections to reflect your group names:

    
    <application type="war" id="jts" name="jts" location="${server.config.dir}/apps/jts.war">
        <application-bnd>
            <security-role name="JazzAdmins">
                <group name="AcmeJazzAdmins" />
            </security-role>
            <security-role name="JazzProjectAdmins">
                <group name="AcmeJazzProjectAdmins" />
            </security-role>
            <security-role name="JazzUsers">
                <group name="AcmeJazzUsers" />
            </security-role>
            <security-role name="JazzGuests">
                <group name="AcmeJazzGuests" />
            </security-role>
        </application-bnd>
    </application>

Caution, be sure to do this for each war file you use. (example, JTS, CCM, etc..)

Complete the JTS Setup

You can now return to the JTS Setup and complete the rest of the SETUP configuration.

Migrating from Tomcat to Liberty Profile

After the upgrade is complete, you will need to complete the LDAP transition prior to trying to log into the server.
At this stage, the upgrade scripts will already have modified the server.xml file to use the ldapUserRegistry. However, you will need to complete the ldapUserRegistry configuration as noted in this article.

Tips and Tricks

• If your applications reside on different servers (Enterprise Deployment Topology) Once you complete the ldapUserRegistry, you can copy this registry to your other servers to use for your other applications.
• Best Practices dictate to always test an upgrade prior to upgrading your Production Environment. Once your testing is done and you are ready to upgrade your Production Environment, you can copy the ldapUserRegistry.xml file from Test to Production if you are using the same LDAP server.
  

Troubleshooting

If you cannot log into the application, then there may be a problem with your User Filter / Member ID. If the Object Class and / or Member ID are not correct in the ldapUserRegistry.xml file, then you will not be able to log into the application. Verify with your LDAP administrator that you have the correct object class for the user filter and the correct Member ID.

If you cannot log into the application, verify that there are no spaces in your "bindDN". For example:
This will throw an invalid password error:
bindDN="cn=Administrator, dc=rtp, dc=raleigh ,dc=ibm, dc=com"
but when changed to:
bindDN="cn=Administrator,dc=rtp,dc=raleigh,dc=ibm,dc=com" it now works. (no spaces after the commas)
You will also see the following error message in the jts.log:

javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C0903D0, comment: AcceptSecurityContext error, data 52e, v2580\u0000]  

If you can log into the application but you get an error message stating that you are not a member of any groups, then the problem is typically with either your group filter object class, your group member ID, or it could be that your BaseDN is too specific. For example, if your BaseDN has something like OU=users it may not be able to read the groups correctly. Talk to your LDAP Admin for the correct BaseDN.

Make sure you ask your LDAP administrator if you need certificates to communicate with the LDAP server. (SSL)

You can enable tracing to help you troubleshoot connection issues by adding the following to the server.xml file:

<logging  traceSpecification="com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all" 
   traceFileName="ldap_trace.log" 
   maxFileSize="20" 
   maxFiles="10" 
        traceFormat="BASIC" /> 

You should enter this after the "< logging hideMessage="SRVE9967W"/>" and before the < /server>.
Be sure to disable this when you resolve your ldap connection issue.
You do NOT have to stop and restart the server to enable or remove tracing. Modify the server.xml file and save the file. Liberty will start to trace. When you are done, you can remove the tracing and simply save the server.xml file.

Question: Do you have Active Directory and need to use nested groups?

Answer: Take a look at this Jazz.net article, Enabling support for chained LDAP groups in Microsoft Active Directory It discusses among other things, a property in JTS Advanced Properties, matching-rule-in-chain capability. Set it to true to enable this capability.

Question: Why does it take a long time to login first time using LDAP configuration?

Answer: It may be necessary to change the value of the referal entry in ldapUserRegistry.xml file. Try changing it From: referal="follow" To: referal="ignore"

Question: You asked for LDAP parameters from your LDAP admin but they did not provide all the info we request. What now?

Answer: For Microsoft AD directory, make sure you select this option in the dropdown, and not custom, so that you at least get the defaults for this LDAP provider. I had one customer who only received a LDAP server name and a base DN. This worked as long as we used the default LDAP properties for Microsoft AD. See attached screenshot.

General Guidelines for LDAP Configurations with Liberty Profile

If the ldapType is:

• Microsoft AD, then the filters used are: activedFilters
• Tivoli, the filters are: idsFilters
• Novell AD, the ldap type is custom and therefore needs customFilters ,
• Apache ldap (or any other 'custom' ldap server.) filters are customFilters
  

Whenever you have custom ldap types, simply copy what is in the "idsFilter" and paste it into the customFilters. At this point you can either remove the idsFilter and contents, comment them out, or leave them. (they are not needed if you have the customFilters for ldapType custom.)

Related topics: Deployment web home, Deployment web home

External links:

• IBM

Additional contributors: RosaNaranjo