Setting up Lotus Quickr services for Lotus Domino with Microsoft Active Directory 

1. Overview

Lotus Quickr Services for Lotus Domino requires some type of directory services to function correctly. These directory services can come from an existing Lotus Domino environment, from an LDAP service or from the local contacts. Each of these allow for the product to authenticate the users, provide for group membership and store meta data about the members.

Leveraging the Lotus Domino directory natively is perhaps the least complicated, but can present challenges when trying to perform product integration with WebSphere Portal, Lotus Sametime, and Lotus Connections. To simplify product integration using the same LDAP source across each is recommended. This means that for a Lotus Domino based directory environment the preferred method is via an LDAP source.

A very common deployment requirement within today's enterprise environment is integration with Microsoft's Active Directory. This directory provides the backbone for all of the Microsoft enterprise solutions in the market today including the Windows operating systems.

2. Review of Active Directory Example Topology

Lotus Quickr can effectively integrate into Microsoft Active Directory with proper planning. The intent of this article is to outline an example Microsoft Active Directory deployment and how to integrate it with Lotus Quickr Domino.

For a more indepth discussion of Active Directory concepts refer to: http://technet.microsoft.com/en-us/library/bb803600.aspx

The diagram show in Figure 1 displays an example of Active Directory Forest for a the Example Corporation. The structure used by Active Directory uses the same format as a DNS service. The root of the structure starts with a tree rooted at example.com. This tree contains a set of domain objects (i.e. users, groups, computers, printers, etc). It also contains a child domain of corp.example.com. This child domain tree also contains the same types of objects, but as described above can be managed independently.

The important aspect of this deployment as related to Lotus Quickr integration is that users could come from any location in the forest (example.com) while groups will only exist under the tree (corp.example.com). This is important because it drives the interface point with the Active Directory environment. If all users and groups existed under the tree corp.example.com then any of its domain controllers could be used as the LDAP source. However, since we need users from a higher level in the tree it changes the interface point to be at the example.com level. An interesting side effect of using the typical port 389 and/or 636 interface is that when accessing users under corp.example.com the object itself is not returned. What is returned is a referral response from the LDAP server. This is a standard way in which an LDAP server can tell the inquiring client I don't have the information you are looking for, but here is a location that it is available.

This presents a challenge with Lotus Quickr as it can't follow LDAP referrals and will result in the objects below corp.example.com as being unavailable. To solve this problem a special service can be used call the Global Catalog. The Global Catalog provides all forest information to be available and searchable using a standard LDAP interface. The important point is that Active Directory will no longer respond using referral responses.

For larger Active Directory deployment the use of the Global Catalog is generally required. It provides for optimal performance of the Active Directory forest to any LDAP applications such as Lotus Quickr. One important aspect is that the Global Catalog only represents a subset of attributes from the Active Directory schema. Using the Microsoft Administrations tools this can be adjusted if needed along with indexing of those attributes.

Reference: Active Directory Schema - http://msdn.microsoft.com/en-us/library/ms675085(VS.85).aspx

3. Integrating with Active Directory

The article assumes that a standard install of Lotus Quickr 8.1 with the latest available hotfix (from fixcentral) has been completed. The base product installation steps are not covered.

The first step after base product installation is to ensure that the Multi Server Single Signon steps have been completed. These steps are covered in detail in the following technote:

How to enable multi-server single sign-on for QuickPlace or Lotus Quickr

http://www-01.ibm.com/support/docview.wss?rs=899&uid=swg21104931

The high level steps to complete this step: (NOTE: I have the images for these steps if needed)

• Create/Update WebSSO document
• Use Configuration Name of LtpaToken
• Use DNS Domain of example.com
• Add participating servers (quickr/Example)
• Create/Import SSO key
• Edit Server document (quickr/Example)
• Set homepage to /LotusQuickr
• Enable Multi Servers (SSO)
• Select Web SSO Configuration: LtpaToken
• Enable Java servlet support: Domino Servlet Manager
• Create domcfg.nsf database
• Map Login form to LotusQuickr/resources.nsf QuickPlaceLoginForm
• Update notes.ini with NoWebFileSystemACLs=1 and h_ScopeUrlInQP=1
• Restart Domino server

At this point the server should have SSO configured and it is possible to login with the local Quickr administrative user ID created during the installation process. In this example the local user is called qradmin. It is important to note that this should not exist in the local Domino or LDAP directory source.

One item commonly overlooked is that a new group should be created in the Lotus Domino directory called QuickPlaceAdministratorsSUGroup. This group will be used for Lotus Quickr administrative access via the Lotus Admin client. The group is in the various Lotus Quickr databases by default and should have the appropriate membership required to manage the Lotus Quickr environment.

4. Enabling Lotus Quickr LDAP Access

The next step in the process is to change the default directory type in Lotus Quickr to LDAP.

This is done by authenticating with an administrative user ID. In this example that would be the local user qradmin. The follow the next set of steps: (NOTE: I have the images for these steps if needed)

• Select Site Administration
• Select User Directory
• Select Change Directory
• Select LDAP Server
• Name: domctrl.example.com
• Note: This is the top root level of the Active Directory Forest
• Port Number: 3268
• Search Base: dc=example,dc=com
• Check to use credentials specified below when searching the directory
• Username: cn=QuickrApp,cn=users,dc=example,dc=com
• Password: <enter appropriate password for Active Directory User account>
• Authentication Timeout (seconds): 10
• Search Timeout (seconds): 10
• Click Next to Save the changes

At this point the Lotus Quickr server will attempt to connect to the LDAP directory source provided and return a status message if successful. The screen capture shown in Figure 2 demonstrates this with the OK with Credentials highlighted section.

Figure 2 LDAP Connection Status

The next step is to update the qpconfig.xml file to refine Lotus Quickr's LDAP settings. The default installation does not create a qpconfig.xml, but instead a file called qpconfig_sample.xml. This file contains an example configuration settings and associated documentation of those setting values.

Copy the qpconfig_sample.xml file to qpconfig.xml and open it with a text editor.

Several sections will be updated from the base configuration.

• Change the My Places page to open in the existing browser window. While not directly related to the LDAP integration it is a very commonly requested change.

<my_places> 
	<place_links open_new_window="false"/> 
</my_places>

• Define the Lotus Quickr super user account/group from the LDAP directory. In this example an Active Directory group called QuickrAdmins is used. This will control global administrative access via with web browser.

<super_user enabled="true"> 
	
<dn>cn=QuickrAdmins,ou=Admins,ou=Groups,dc=example,dc=com</dn> 
</super_user>

• Update the <user_directory> section to make the necessary Active Directory adjustments.

<user_directory> 
	<ldap> 
	 <base_dn> 
	  <group>dc=corp,dc=example,dc=com</group> 
	 </base_dn> 
	 <schema> 
	  <object_class>objectClass</object_class> 
	  <user> 
	   <object_class_value>person</object_class_value> 
	   <common_name>cn</common_name> 
	   <display_name>displayName</display_name> 
	   <first_name>givenName</first_name> 
	   <last_name>sn</last_name> 
	   <email>mail</email> 
	   <phone>telephoneNumber</phone> 
	  </user> 
	  <group> 
	   <object_class_value>group</object_class_value> 
	   <common_name>cn</common_name> 
	   <display_name>displayName</display_name> 
	   <member>member</member> 
	   
<attribute_in_person_record>memberOf</attribute_in_person_record> 
	  </group> 
	  <ldap_is_active_directory enabled="true" /> 
	  <do_not_deref_for_groups enabled="true" /> 
	  <dn_delimiter robust_compare="false"/> 
	  <dn_incoming_is_native enabled="false"/> 
	  <secondary_cn_component enabled="true"/> 
	  <maintain_escape_character enabled="false"/> 
	 </schema> 
	 <search_filters> 
	  <authentication> 
	   <![CDATA[ 
	   (|(cn={0})(sAMAccountName={0})) 
	   ]]> 
	  </authentication> 
	  <user_lookup> 
	   <![CDATA[ 
	   (&(objectCategory=Person)(sn={0})(givenName={1})) 
	   ]]> 
	  </user_lookup> 
	  <group_lookup> 
	   <![CDATA[ 
	   (&(objectCategory=Group)(cn={0})) 
	   ]]> 
	  </group_lookup> 
	  <group_membership> 
	   <![CDATA[ 
	   (&(objectCategory=Group)(member={0})) 
	   ]]> 
	  </group_membership> 
	 </search_filters> 
	 <member_lookup_ui> 
	  <column_name> 
	   <person>sn, givenName</person> 
	  </column_name> 
	  <column_disambiguate> 
	   <person>dn</person> 
	  </column_disambiguate> 
	 </member_lookup_ui> 
	 <search_ui_hint> 
	  <![CDATA[ 
	  ( enter <B>last name, first name</B>) 
	  ]]> 
	 </search_ui_hint> 
	 <search_ui_index>sn</search_ui_index> 
	 <ssl protocol="3" accept_expired_certs="true" 
verify_servername="true"/> 
	</ldap> 
</user_directory> 

• Save the qpconfig.xml and restart the Lotus Quickr server

At this point you should be able to authenticate using any of the Active Directory user accounts.

Note: The configuration file above should work for most Active Directory configurations. However, there could be specific changes required for some deployments. Any changes to production systems should be tested prior to implementation.

5. Troubleshooting LDAP connectivity

If there are issues connecting to the LDAP source or the desired results are not being returned a few avenues are available to diagnose the situation.

Notes.ini – LDAPDEBUG=7

Lotus Quickr uses the LDAP libraries in the core Lotus Domino product as such the LDAP debug notes.ini setting will display all requests made. This can be valuable in determining if the correct requests and associated results are being exchanged.

Notes.ini – QuickPlaceUserDirectoryLogging=1

Notes.ini – QuickPlaceAuthenticationLogging=5

Lotus Quickr has additional logging options for the core subsystems of the product. These settings can expose additional issues such as name transformation or group expansion.

Network Sniffer – These are software applications or network appliances that can capture the actual network communication between the Lotus Quickr server and the LDAP source. For example one popular solution in this area is WireShark http://www.wireshark.org (formally known as Ethereal). It is important to get permission from the network and security teams before running these types of applications within the network.

6. SSL Enablement

Lotus Quickr can leverage SSL encrypted LDAP sources if required. Since the product uses the native Lotus Domino LDAP libraries the same process to enable SSL is used. For Microsoft Active Directory this involves the following steps: (NOTE: I have the images for these steps if needed)

• Open the Server Certificate database (certsrv.nsf)
• Create a new Key Ring
• Export the Microsoft Certificate Authority Key used to create the Active Directory SSL certificate
• Exporting from Internet Explorer is generally easiest or from the Microsoft Certificate Server if used.
• Import the Trusted Root Certificate into the Key Ring
• Copy Key Ring files (.kyr and .sth) files to the Lotus Quickr Server
• Add Key Ring file name copied above to Lotus Quickr server document
• Restart Lotus Domino Server
• Log into Lotus Quickr as administrative user
• Open Site Administration
• Open User Directory
• Click Change Directory
• Change the port number to 3269 (SSL Global Catalog)
• Check for SSL connection with LDAP User Directory
• Click Next to save changes
• Validate the OK with Credentials message is displayed
• Restart Lotus Quickr server (HTTP task can be restarted)

At this point the Lotus Quickr should be using SSL for all LDAP traffic. One important thing to note is that SSL is host name specific. This is similar to the warning message displayed in a web browser when hitting a site that has a mismatching SSL certificate name. In the example configuration above the LDAP server host name is domctrl.example.com and the SSL certificate common name matches. However, if the host name is changed to ldap.example.com then the name will not match and LDAP will not function correctly. This is fairly common if the LDAP server is behind an IP Sprayer or an alternate CNAME is defined for it in DNS.

To correct this issue the setting <ssl verify_servername="false"/> needs to be added into the <user_directory><ldap>....</ldap></user_directory> section of the qpconfig.xml. This will prevent the name comparison issue.

7. Summary

Lotus Quickr can be effectively integrated into a Microsoft Active Directory environment. The key points are care planning and testing of the configuration. This article will provide you an example environment that will provide a working configuration. There may need to be adjustments made for certain directory configurations.

Notes

Article by: David Byrd, Executive I/T Architect - IBM Software Services for Lotus

Editing note:This content is not available to be edited at this time. However, comments are welcome.