ShowTable of Contents
Overview
In Quickr version 8.1, if you have an LDAP directory and want to use it as a user repository for Lotus Quickr, you can use the configuration wizard with the “Standalone LDAP option” to finish the configuration. But what happens if you have two LDAP directories? Can you still use the configuration wizard or some other tasks?
The answer is “No,” because Lotus Quickr 8.1 is based on IBM WebSphere Portal 6, which supports only the standalone LDAP directory as a user repository.
Of course, you might assume that is no problem because you can use migration tools to merge these two LDAP directories into a new one, and then use the configuration wizard. However, if these two LDAP directories are being used by several existing applications, how do you synchronize the user information with all existing applications? These are the kinds of issues that often annoyed users of Quickr 8.1.
Fortunately, Quickr 8.5 has been moved onto WebSphere Portal 6.1, which has a new feature called federated repository that allows Lotus Quickr to support multiple LDAP directories. In other words you can now combine multiple LDAP directories into a federated LDAP user registry without having to any external tools.
Prerequisites
Before starting to configure multiple LDAP directories as a federated LDAP user registry for Quickr 8.5, you should complete the following:
- Refer to the User IDs and passwords topic of the WebSphere Portal 6.1.5 Information Center, for the character limitations of the user IDs and passwords.
- Ensure that the user IDs that are unique between the current federated repository and the LDAP you are adding. For example, if the current federated repository contains an ID such as wpsadmin, this ID cannot exist in the LDAP you are adding.
- Read the Configuration task properties topic in the InfoCenter.
Configuration steps
Generally, you can follow the manual steps illustrated below to configure an LDAP server for Lotus Quickr for WebSphere Portal 8.5. Of course, Lotus Quickr also provides a configuration wizard tool with which you can perform common LDAP configurations, including adding/deleting an LDAP, and switching an LDAP while either changing or not changing the Administration users.
Standalone Lotus Quickr
Adding a federated LDAP
To do this, you can either follow Steps 1-2, 9 & 13 in Section 3 below, or use the flowchart in figure 1.
Figure 1. Process to add LDAP repository
Deleting a federated LDAP
To do this, you can either follow Steps 1, 6, 9 &13 in Section 3, or use the flowchart in figure 2.
Figure 2. Deleting LDAP repository
Switching a federated LDAP while not changing the Admin users/groups
To do this you can either follow Steps 1-2, 6, 9 & 13 in Section 3 or use the flowchart in figure 3.
Figure 3. Switching LDAP repository, not changing admin users
Switching a federated LDAP while changing the Admin users/groups
To do this, you can either follow Steps 1-6, 9-10, 13-15 in Section 3, or use the flowchart in figure 4.
Figure 4. Switching LDAP repository while changing admin users
Clustered Lotus Quickr
All cluster LDAP configuration processes, except restarting nodes and servers, are executed on the primary node, so each configuration task is needed only by the primary node.
Adding a federated LDAP
To do this, you can either follow Steps 1-2, 7-9 & 11-13 in Section 3 or use the flowchart for standalone Lotus Quickr (recall figure 1).
Deleting a federated LDAP
To do this, you can either follow Steps 1, 6, 7-9 & 11-13 in Section 3 or use the flowchart for standalone Lotus Quickr (recall figure 2).
Switching a federated LDAP while not changing the Admin users/groups
To do this, you can either follow Steps 1-2, 6-9 & 11-13 in Section 3 or use flowchart for standalone Lotus Quickr (recall figure 3).
Switching a federated LDAP while changing the Admin users/groups
To do this, you can either follow all the steps in Section 3, one by one, or you can use the flowchart for stand-alone Lotus Quickr (recall figure 4).
Complete configuration steps
NOTE: The parent.properties file for specific information about the required parameters and for advanced parameters. Enter the values for the all required parameters in the parent.properties file given by each step.
<wp_profile_root>: Replace with the profile location, e.g., C:/IBM/Quickr/wp_profile
<parent_file_dir>: Replace with the parent file location, e.g., C:
<log_path>: Replace with the log file location: e.g., C:
<dmgr_profile_root>: Replace with the Deployment Manger profile location, e.g. C:/IBM/ WebSphere
1. (Optional) Validate your LDAP server settings:
a. Create a file named parent.properties, copy the contents in listing 1, and input the required properties.
Listing 1. parent.properties for step 1
# Required
# The implementation class name for the repository adapter.
# The default value is com.ibm.ws.wim.adapter.ldap.LdapAdapter
federated.ldap.adapterClassName=com.ibm.ws.wim.adapter.ldap.LdapAdapter
# Required
# Specifies whether to map X.509 certificates into a LDAP directory by exact distinguished name or certificate filter.
# Specify the certificate filter to use the specified filter for the mapping, if client certificate authentication is used
# for portal server.
# Valid values include: EXACT_DN, CERTIFICATE_FILTER
federated.ldap.certificateMapMode=EXACT_DN
# Required
# Indicates the authentication method to use. The default value is simple. Valid values include: none or strong.
federated.ldap.authentication=simple
# Controls how aliases are dereferenced. The default value is always. Valid values include:
# always - always deference aliases
# never - never deference aliases
# finding - deference aliases only during name resolution
# searching - deference aliases only after name resolution
federated.ldap.derefAliases=always
# Required
# The LDAP referral. The default value is ignore. Valid values include: ignore, follow, throw, or false.
federated.ldap.referral=ignore
# Optional
# Specifies the filter certificate mapping property for the LDAP filter, if client certificate authentication is used
# for portal server.
# The syntax or structure of this filter is: LDAP attribute=${Client certificate attribute} (for example, uid=${SubjectCN})
# The filter is used to map attributes in the client certificate to entries within the LDAP repository.
federated.ldap.certificateFilter=
#########################
# Group member attributes
#########################
# Required
# The name of the LDAP attribute that is used as the group member attribute. For example, member or uniqueMember.
federated.ldap.gm.groupMemberName=
# Required
# The group object class that contains the member attribute. For example, groupOfNames or groupOfUnqiueNames.
# If you do not define this parameter, the member attribute applies to all group object classes.
federated.ldap.gm.objectClass=
# Required
# The scope of the member attribute. The valid values for this parameter include the following:
# direct - The member attribute only contains direct members.
# nested - The member attribute that contains the direct members and the nested members.
federated.ldap.gm.scope=direct
# Optional
# If you create a group without specifying a member, a dummy member will be filled in to avoid creating an exception about missing a mandatory attribute.
# With Active Directory , Sun One & Novell eDir the value has to be empty or point to an existing entry in the LDAP directory
federated.ldap.gm.dummyMember=
############################################
#
# LDAP entity types
#
# The supported entity types are
# Group
# default searchFilter = <empty>
# default objectClasses = groupOfNames
# default objectClassesForCreate = groupOfNames
# default searchBases = <empty>
# PersonAccount
# default searchFilter = <empty>
# default objectClasses = inetOrgPerson
# default objectClassesForCreate = inetOrgPerson
# default searchBases = <empty>
#
############################################
# Entity type Group
# Optional
# The search filter that you want to use to search the entity type.
# VMM uses this filter as an addition during search requests in your environment
# The syntax is like a standard LDAP searchfilter like (objectclass=groupOfUniqueNames)
# In general this value can be left blank
federated.ldap.et.group.searchFilter=
# Required
# One or more object classes (separated by ';') for the entity type.
federated.ldap.et.group.objectClasses=group
# Optional
# The object class(es) (separated by ';') to use when an entity type is created. If the value of this parameter is the same as the objectClass parameter, you do not need to specify this parameter.
federated.ldap.et.group.objectClassesForCreate=
# Optional
# The search base or bases to use while searching the entity type.
federated.ldap.et.group.searchBases=
# Entity type PersonAccount
# Optional
# The search filter that you want to use to search the entity type.
# VMM uses this filter as an addition during search requests in your environment
# The syntax is like a standard LDAP searchfilter like (objectclass=inetOrgPerson)
# In general this value can be left blank
federated.ldap.et.personaccount.searchFilter=
# Required
# One or more object classes (separated by ';') for the entity type.
federated.ldap.et.personaccount.objectClasses=user
# Optional
# The object class(es) (separated by ';') to use when an entity type is created. If the value of this parameter is the same as the objectClass parameter, you do not need to specify this parameter.
federated.ldap.et.personaccount.objectClassesForCreate=
# Optional
# The search base or bases to use while searching the entity type.
federated.ldap.et.personaccount.searchBases=
# Required
# The id specifies a unique identifier for the repository within the cell
# Characters that are not allowed in normal XML strings ( & < > " ' ) cannot be used in the repository ID.
federated.ldap.id=
# Required
# Specifies the host name of the primary LDAP server. This host name is either an IP address or a domain name service (DNS) name.
federated.ldap.host=
# Required
# Specifies the LDAP server port.
federated.ldap.port=389
# Required
# Specifies the distinguished name for the application server to use when binding to the LDAP repository.
federated.ldap.bindDN=
# Required
# Specifies the type of LDAP server to which you connect
# On WAS 6.1 this must be one of the following values: SECUREWAY,IDS4,IDS51,IDS52,IDS6,ZOSDS,DOMINO5,DOMINO6,DOMINO65,DOMINO7,NDS,SUNONE,AD2000,AD2003,ADAM,CUSTOM
# Note: for ActiveDirectory 2008 use AD2003 as value
# Note: If your LDAP server version is not listed, enter the value for the highest listed version of your server e.g use AD2003 if you have Active Directory 2008
# On WAS 7 this must be one of the following values: IDS, ZOSDS, DOMINO, NDS, SUNONE, AD, ADAM, CUSTOM
federated.ldap.ldapServerType=
# Required
# The LDAP base entry.
federated.ldap.baseDN=
# Required
# Indicates the property name used for login. Common values include: uid or cn
federated.ldap.loginProperties=
2. (Required) Add a LDAP user registry to the default federated repository:
3. (Required) Change the WebSphere Application Server (WAS) admin user:
NOTE: The new WAS Admin user you provide must be a unique user in the federated repository.
a. Create a file named parent.properties, copy the contents shown in listing 2, and input the required properties.
Listing 2. parent.properties for step 3
# Required
# newAdminId: The full form of user ID for the WebSphere Portal Administrator in ldap server.
newAdminId=
b. Run the ConfigEngine task as follows:
<wp_profile_root>/ConfigEngine/ConfigEngine.bat(or ConfigEngine.sh) wp-change-was-admin-user -DparentProperties="<parent_file_dir>/parent.properties" -DSaveParentProperties=false -DnewAdminPw=<ReplaceWithNewPwd> -DWasUserid="<ReplaceWithYourWasUserid>" -DWasPassword=<ReplaceWithYourPwd> -Dskip.ldap.validation=true 2>&1 > "<log_path>/log03.log"
4. (Required) Change the Portal admin User and group:
NOTE: The new Portal Admin user and group you provide must be a unique user/group in the federated repository.
a. Create a file named parent.properties, copy the contents as below and input the required properties.
Listing 3. parent.properties for step 4
# Required
# newAdminGroupId: The full form of group ID for the WebSphere Portal Administrator in ldap server.
newAdminGroupId=
# Required
# newAdminId: The full form of user ID for the WebSphere Portal Administrator in ldap server.
newAdminId=
5. (Optional) Update the Group and PersonAccount entity types with the corresponding default parent and relative distinguished name (RDN):
a. Create a file named parent.properties, copy the contents in listing 4, and input the required properties.
Listing 4. parent.properties for step 5
# Required
# The RDN attribute names for the entity types PersonAccount and Group
# To reset all the values of the rdnProperties parameter, specify a blank string ("").
personAccountRdnProperties=
groupRdnProperties=
# Required
# The default parents of the entity types PersonAccount and Group
personAccountParent=
groupParent=
b. Run the ConfigEngine task as follows:
<wp_profile_root>/ConfigEngine/ConfigEngine.bat(or ConfigEngine.sh) wp-set-entitytypes -DparentProperties="<parent_file_dir>/parent.properties" -DSaveParentProperties=false -DWasUserid="<ReplaceWithYourWasUserid>" -DWasPassword=<ReplaceWithYourPwd> 2>&1 > "<log_path>/log05.log"
6. (Required) Delete a repository:
a. Create a file named parent.properties, copy the contents in listing 5, and input the required properties.
Listing 5. parent.properties for step 6
# Required
# The ID of the repository to be deleted from the VMM configuration
# This parameter must be set to LA if you want to delete the property extension repository.
federated.delete.id=
# Required
# The name of the base entry to be deleted from the default realm.
# If the base entry exists in other realms, it has to be deleted manually first.
# Leave this empty only if you want to delete the property extension repository.
federated.delete.baseentry=
7. (Required only for clusters) Stop the Deployment Manager (DM) by running the following command:
<dmgr_profile_root>/bin/stopManager.bat(or stopManager.sh) -username "<ReplaceWithYourWASAdmId>" -password <ReplaceWithYourWASAdmPassword>
8. (Required only for clusters) Stop all nodes by running the following command:
<wp_profile_root>/bin/stopNode.bat(or stopNode.sh) -username "<ReplaceWithYourWASAdmId>" -password <ReplaceWithYourWASAdmPassword>
9. (Required) Stop all servers (including WebSphere Portal server and WAS server) by running the following commands:
<wp_profile_root>/bin/stopServer.bat(or stopServer.sh) WebSphere_Portal -username "<ReplaceWithYourPortalAdmId>" -password <ReplaceWithYourPortalAdmPassword>
<wp_profile_root>/bin/stopServer.bat(or stopServer.sh) server1 -username "<ReplaceWithYourPortalAdmId>" -password <ReplaceWithYourPortalAdmPassword>
10. (Required) Apply the security ifixes for Quickr for WebSphere Portal 8.5:
NOTE: Be sure to use the RDN instead of the DN as the user id and group id for this step.
Run the ConfigEngine task as follows:
<wp_profile_root>/ConfigEngine/ConfigEngine.bat(or ConfigEngine.sh) action-security-ifixes-for-qkr -DPortalAdminId="<ReplaceWithYourNewPortalAdmId>" -DPortalAdminPwd=<ReplaceWithYourPortalAdmPassword> -DPortalAdminGroupId="<ReplaceWithYourNewPortalAdmGroupId>" -DWasUserid="<ReplaceWithYourNewWasUserid>" -DWasPassword=<ReplaceWithYourPassword> 2>&1 > "<log_path>/log10.log"
11. (Required only for clusters) Start DM by running the following command:
<dmgr_profile_root>/bin/startManager.bat(or startManager.sh) -username "<ReplaceWithYourWASAdmId>" -password <ReplaceWithYourWASAdmPassword>
12. (Required only for clusters) Start all node agents by running the following command:
<wp_profile_root>/bin/startNode.bat(or startNode.sh) -username "<ReplaceWithYourWASAdmId>" -password <ReplaceWithYourWASAdmPassword>
13. (Required) Start all servers (including Portal server and WAS server) by running the following commands:
<wp_profile_root>/bin/startServer.bat(or startServer.sh) WebSphere_Portal
<wp_profile_root>/bin/startServer.bat(or startServer.sh) server1
14. (Required) Change content groups:
a. Create a file named parent.properties, copy the contents in listing 6, and input the required properties.
Listing 6. parent.properites for step 14
# PortalAdminIdShort: The short form of user ID for the WebSphere Portal Administrator in ldap server.
# See LDAP examples below:
# IBM Directory Server: { uid=<wasuserid>,cn=users,dc=yourco,dc=com } short form: <wasuserid>
PortalAdminIdShort=
# PortalAdminPwd: The password for the WebSphere Portal Administrator
PortalAdminPwd=
#####################################################################
# Properties required for importing and exporting of migration data
#####################################################################
# Required
# Using the full group name in ldap server
WpsContentAdministrators=
b. Run the ConfigEngine task as follows:
<wp_profile_root>/ConfigEngine/ConfigEngine.bat(or ConfigEngine.sh) action-configure-content-groups-for-pdm -DparentProperties="<parent_file_dir>/parent.properties" -DSaveParentProperties=false -DWasUserid="<ReplaceWithYourNewWasUserid>" -DWasPassword=<ReplaceWithYourPwd> 2>&1 > "<log_path>/log14.log"
15. (Required) Adapt the mail attribute for the person card by running the ConfigEngine task as follows:
<wp_profile_root>/ConfigEngine/ConfigEngine.bat(or ConfigEngine.sh) wp-update-federated-ldap-attribute-config -Dfederated.ldap.attributes.mapping.ldapName="mail,title" -Dfederated.ldap.attributes.mapping.portalName="ibm-primaryEmail,ibm-jobTitle" -Dfederated.ldap.attributes.mapping.entityTypes="PersonAccount,Group" -DWasUserid="<ReplaceWithYourNewWasUserid>" -DWasPassword=<ReplaceWithYourPwd> 2>&1 > "<log_path>/log15.log"
Troubleshooting
Issue: You encounter an error during the LDAP configuration process.
Issue: You receive a connection error from the validation task, even though you can reach the target LDAP directory via PING. The error message may be something like “A connection to the server could not be established....”
Resolution: For some complex network situations, PING is not enough to prove that both the Quickr server and LDAP server can be connected with each other. You can try using TELNET instead of PING to test the network. If you have a connection issue, you must contact your internal IT group to resolve the network issue, and then try re-running the LDAP configuration tasks.
Issue: A user who is registered in LDAP repository is not able to sign in to Lotus Quickr after LDAP is configured successfully.
Resolution: Check whether the expected user is under the Base DN you specified during the LDAP configuration.
Issue: In a cluster environment, LDAP configuration tasks fail to run or, after finishing configuring LDAP successfully, you are not able to use Lotus Quickr.
Resolution: The issue might be caused by the synchronization from DM to each node so, before you begin to run configuration tasks or after you restart the cluster environment, be sure that all nodes have been synchronized with DM.
Issue: Users who belong to a LDAP repository cannot log in to Lotus Quickr and cannot even be found in place member management, but they can be found in the WebSphere Portal user management portlet.
Resolution: The problem may be caused by the bind user, who is used to configure the LDAP server and does not have sufficient permissions to add members. If so, go to the LDAP server side and give the bind user the necessary permissions.
Conclusion
This article has described via graphics and via textual steps how to configure federated LDAP for Lotus Quickr 8.5 for WebSphere Portal and how to troubleshoot some common issues.
Resources
Refer to the
Lotus Quickr 8.5 for WebSphere Portal documentation.
Refer to the
WebSphere Portal 6.1.5 documentation.
Read the developerWorks article, “
IBM Lotus Quickr 8.5 security: Configuring federated IBM Directory LDAP Server security using the Configuration Wizard.”
About the authors
Yue Zhang has served as the FVT Install Test team lead for Lotus Quickr 8.5 for WebSphere Portal since February 2009. You can reach her at
zhyuecdl@cn.ibm.com.
Jin Yin serves as the Lotus Quickr 8.5 for WebSphere Portal developer in charge of Configuration Wizard development. You can reach him at
yinjin@cn.ibm.com.