Blog

Blog Search

Search this site

Advertisements

Everything Else

Sponsor

Wood Watch Review

Google Custom Searches

Custom Blogger Search
Custom Sametime Search
Custom XPages Search

Subscribe

Subscribe via RSS

Recent Tweets

Hosting by

You are here: Home › Blog

E-Pro: Using LDAP in Domino


Tags :


Using LDAP in Domino

by Chris Miller
Lightweight Directory Access Protocol (LDAP) is a TCP/IP protocol that was designed as a lightweight option to Directory Access Protocol (DAP) to access X.500 directories. LDAP defines a standard way to search for and manage entries in a directory, where an entry is one or more groups of attributes that are associated with a distinct name. LDAP provides a format that defines the communication between the server and client for X.500 directory searches. Binding occurs when a client opens a session with an LDAP server. The client then searches based on anonymous rights or is authenticated (if offered the opportunity) to gain more privileges.
       People often say that they’re “implementing an LDAP directory.” What they really mean is that they’re implementing an LDAP-accessible directory. An LDAP directory can contain many types of entries  for example, entries for users, groups, devices, and application data.
Before LDAP, as each network and application grew, so did the number of unique directories. Each directory became an island that was unreachable from the others. LDAP evolved to address this problem, and vendors have embraced it. LDAP is appearing frequently in many software packages as a way to offer directory integration. Even Sun recently used LDAP as a directory infrastructure in Solaris 9.
Lotus began offering LDAP capabilities in Domino version 4.6x, and R5 included many enhancements. Here, I’ll explore how to configure and use LDAP effectively and troubleshoot common errors in Domino R5.

Domino LDAP Security
Before you open your Domino Directory to LDAP searches, you should review which fields you’re making available (for security purposes) and which policies you’ll set regarding directory updates via LDAP. Although opening your directory to the public for searches of e-mail addresses or phone numbers might be beneficial, it may not be a good idea to make available certain information that’s enabled by default, such as Location. On the LDAP tab in the Server Configuration document in the Domino Directory (Figure 1), you can configure the fields that users with anonymous access are allowed to search.
Domino integrates the security policy of the Access Control List (ACL) into LDAP to authenticate users wanting more access to information or more permission for directory management. You can let users update entries via LDAP by setting at least Editor access or Author access with additional roles in the ACL of the Domino Directory. You must also enable the “Allow LDAP users write access” setting in the Server Configuration document (Figure 1). After you select Yes at this field, authenticated LDAP users can make adds, deletes, and modifications based on the roles and rights in the ACL.
If you don’t allow anonymous access and require all users to provide a name and password to authenticate, you have options for forcing users to provide their user (short) names or their more specific, fully qualified, distinguished names. By default, Domino LDAP uses the short name option. The only way to enable the more specific option, which refers to RFCs 2251 through 2254, is to add a line to the Notes.INI of the server:

LDAP_Strict_RFC_Adherence=1

Once you have this Notes.INI setting in place and restart the LDAP server task on Domino, users can authenticate using only their hierarchical names. For example, Bob Jones/Sales/Corp can authenticate, but Bob Jones or bjones can’t.
Authentication options for allowing anonymous access are set in the Domino Server document. Select Ports, Internet Ports, and the Directory tab. As long as “TCP/IP port status” is enabled, you can answer Yes or No to allowing Name & Password and Anonymous access from LDAP clients. If you do allow Anonymous access, I’ll cover how to set which fields are available to Anonymous access in a moment.

Loading LDAP on Domino the First Time
One configuration item that confused me at first is how Domino offers LDAP configuration. You can set advanced LDAP settings (e.g., timeout values, anonymously queryable fields) in the Server Configuration document. But this tab is only available if you select the option “Use these settings as the default settings for all servers” on the Basics tab.
       Basically, there is one default document for your domain that controls LDAP for all servers. You specify LDAP settings for all servers in the domain in one general configuration. Don’t create a specific Configuration document for the server running LDAP or you’ll lose the LDAP tab. Lotus designed this feature to ease administration by listing information in one global document. But sometimes you need to maintain different LDAP settings for different servers; for example, some company staff settings might be inside the firewall, and those for business partners and customers may be in the DMZ.
       A common misconception about the timeout setting on the Server Configuration document for LDAP is that connections are dropped after the timeout period specified. (This timeout is for LDAP searches only and not actual connections to the LDAP server.)
Loading LDAP on your Domino R5 server for the first time is as simple as typing load ldap on the server console. This starts the LDAP server task and lets LDAP clients make inquiries against your Domino directory.
       One immediate error message that may appear is, “LDAP Server: Error reading configuration settings, check server and domain configuration records . . . LDAP Server: Initialization failure.” This error occurs when LDAP Port 389 is set to Disable in the Server document. The problem is easily remedied by editing the document in the Domino Directory for the server running the LDAP task. Select Ports, Internet Ports, and the Directory tab, and notice the TCP/IP port status field. Before loading LDAP, verify that this field is set to Enable (unless you’ll be using LDAP only over an SSL or Simple Authentication and Security Layer (SASL) connection).
If you choose SASL in your LDAP solution, there are a few items you should be familiar with. No protocol other than LDAP has the ability to utilize SASL. Domino integrates SASL into the LDAP server. Administratively, you need only enable SASL and go to the same Server document tabs as above and enable the SSL port for LDAP. The connecting LDAP client must also support SASL, of course, and when it connects, the Domino server automatically initiates an SASL session. For more information about SASL, consult RFCs 2222 and 2444 at http://www.rfc-editor.org/rfc.html. SASL is still evolving, so expect modifications.

Performance Enhancement Opportunities
Lotus offers one main option to enhance LDAP performance: Create a full-text index of the Domino Directory on the server running LDAP. (This is for cases in which you’re only looking up names of users.) As Domino uses the ($users) view first, full-text indexing  isn’t necessary in such cases, so you use resources maintaining the full-text index.
       The Domino LDAP task also allows (by default) searches to take as long as necessary when a query is made from an LDAP client. If your server performance slows, set limits for the timeout and maximum number of entries returned on searches. These configuration options are also found in the Server Configuration document. But if an LDAP client also has the ability to control these settings, the one with the lower setting takes precedence.
       One other area that can affect performance is the setting you configure for search results returned and the number of wildcards allowed. The setting lets you specify the number of characters that an LDAP client must place before the wildcard search (*) in the request. The default number of characters is 1. If performance is slow, and you’re aware that LDAP clients are performing searches, try increasing this value to 2. This simply requires the LDAP client to make a more specific search, so the lookup also returns fewer entries to the client.
Some caveats exist. If the LDAP client attempts to use a wildcard as the first character (e.g., *ones), then Domino drops the first wildcard (unless “Minimum characters for wildcard search” is set to 0) and proceeds with the remainder of the search without it. To take this one step further, let’s say the search was cn=*h* and the minimum number of characters required for a search was set to 2. Domino ignores the first wildcard (*) and then rejects the entire search because the user didn’t specify two characters and the other wildcard (*) was at the end.
Also, the “Minimum characters for wildcard search” won’t apply to the LDAP client search if the only character sent in the search is a wildcard. Basically, you use that type of search only to see if a specific LDAP attribute exists. You can still set the “Maximum number of entries returned” configuration setting if you’re concerned about performance hits from that search type.

LDAP Capabilities in Domino
Overall, the directories in Domino aren’t updated as often as they are searched or read. I’ve heard many administrators say that no one even reads their Domino Directories, and they don’t keep anything other than the items created at registration in the Person record. But the server reads the Domino Directory consistently, checking access rights and configurations. Most administrators never realize how often the Directory is read until it breaks.
       LDAP searches the Domino Directory in a certain order, looking for requested information. The order of the search is as follows:

1. The ($users) view
2. The full-text index
3. If there is no full-text index, the ($PeopleGroupHier) view

If the LDAP client makes an attribute request, such as a spouse’s name, the Domino LDAP task goes directly to the full-text index. If there is no full-text index, it goes to the ($PeopleGroupHier) view.
       I recently had a client ask for the ability to synchronize a Domino Directory by pulling updates from another existing LDAP-accessible directory. Domino doesn’t currently let you pull updates from another directory via LDAP. This is possible if you choose to make all initial changes in Domino and then let some third-party LDAP directory connect and update itself from Domino. You’ll need to check with the third-party vendor to verify that its product has that capability.
       Domino R5 also has the ability to export the Domino Directory into Lightweight Data Interchange Format (LDIF). LDIF is the RFC-compliant format that LDAP servers and clients adhere to in building their LDAP schemas. You can retrieve the exported file via a simple command at the Notes client command line:

ldapsearch -h  LDAPservername objectclass =
* > filename.txt

You can then import the specified output file to another LDAP server. I’ll say more about LDAP schemas in a moment.
       Not all fields are available for LDAP searching. Resource documents are one such field. Resources are an object class of a database, which excludes them. When you’re configuring LDAP fields in the Server Configuration document, some of these excluded fields show as choices, but they aren’t valid. For a complete list of fields that are excluded from LDAP accessibility, see technote #190495 at http://www-3.ibm.com/software/lotus/support.
       Groups in a Domino Directory serving LDAP requests are also handled differently if your groups contain spaces. When an LDAP client makes a request for the e-mail address of a group that’s stored with a space, the LDAP server returns underscores where the spaces were. This is because spaces in Internet addresses aren’t valid SMTP characters. Of course, mail to this address will fail because it’s not valid in the Domino Directory. You can correct this by editing the Group document and filling in the Internet Address field on the Basics tab. All LDAP client searches will then return a valid Internet address that can accept mail properly.
       If you use LDAP queries for Web authentication on your Domino server, you must enter names differently within ACLs for users to authenticate correctly. LDAP retrieves names in full canonical format. A returned result looks like “CN=Bob Jones/OU=Sales/O=Corporation”. This is the exact name you’ll then list in the ACL for a user authenticating via a Domino LDAP lookup. (Of course, if the user is a member of a group, the group must exist in the primary Domino directory.)
On the Notes client side, I once had a client request the ability to search each LDAP-accessible directory individually from the Notes client. Currently, you create an Account document in a user’s Personal Address Book (PAB) to selectively search one of multiple secondary address books via LDAP. Lotus documents this ability as an enhancement request. This situation also involves type-ahead addressing from the Notes client. In R5, you can’t get type-ahead features to work when addressing a mail message. You must hit F9, which invokes the namelookup, to get an address-choice list to appear.
       The Notes client may also encounter an issue with searching for groups that Domino accesses via LDAP rules in a Directory Assistance database. Domino stores groups in a flat naming convention, and creating a rule to search for anything but the default of */*/*/*/*/* (see Figure 2) won’t return that group. For example, say you create a rule based on */*/*/*/Company/US for all searches related to that LDAP directory. If you want the group to show in a search with those restrictions, each group must be created hierarchically. Refer to technote #180188 for more information.

Working with the Domino LDAP Schema
A schema is a map of LDAP attributes to the actual record stored in the directory. Any software that provides an LDAP-accessible directory uses schemas. Domino R5 offers special forms with mapping information in the Domino Directory that link to other forms. This gives the LDAP task access to virtually all the information stored in it.
       It’s possible to get errors related to loading the LDAP schema. One reason that such errors occur is if one of the LDAP forms is corrupted or was customized incorrectly. The LDAP task can’t reconcile the schema. This, in turn, shows the LDAP task closing immediately after loading it. For this type of error, you can add a line to the Notes.INI file to show the form (or the directory) that’s not functioning correctly:

DEBUG_LDAP_SCHEMA=1
DEBUG_OUTFILE=

Keep in mind that this will continue to run and create an output file as long as the Notes.INI variable is in place.
       A couple of options let you retrieve information about the schema that Domino provides on your Domino LDAP server. The most user-friendly selection is the Domino LDAP Schema database (SCHEMA50.NSF). That database is created in the data directory if you use the following command on the Domino server console:

tell LDAP exportschema

Make sure you have the database closed before running the console command, or the export into it won’t function. You can run this command as often as necessary to update the database when you make schema changes.
The Designer task that normally runs on your Domino server also updates this database (or creates it for the first time) after loading the schema into memory. The Domino LDAP Schema database provides extensive information on attributes. I suggest opening and becoming familiar with this database after loading LDAP. You can even do full-text searches in the database by default  after the full-text index is created, of course.
       You may also use the ldapsearch utility mentioned earlier with some other options or any LDAP V3-compliant client. A sample command to retrieve the directory schema is:

ldapsearch -h hostname -b "cn=schema" -s base "(objectclass=subschema)">filename.txt

This creates an output in text format. Although it’s not as user-friendly, other LDAP directories can import this type of output.
       It’s also possible to extend the Domino schema by adding attributes and object classes to it. You do this by using Domino Designer and creating new or modifying existing subforms and forms within the Domino Directory. Any time you extend the schema, you can enter “tell ldap reloadschema” at the Domino server console to put the new schema into memory. Then, use the above export server command to put the schema into the Domino LDAP Schema database.
       The LDAP service in Domino doesn’t perform schema checking by default. You must manually enable it by editing the Notes.INI file with the line

LDAP_Enforce_Schema=1

You must then restart the Domino LDAP server task for this to take effect. Once enabled, LDAP will only accept modifications that already conform to the directory schema. The Domino directory LDAP attributes and content are then kept under control. Keep in mind that schema checking is based on the primary Domino Directory. If you use Directory Assistance and have customized those designs, you must also make those changes to the primary Domino Directory for schema checking to function correctly. If any check of the schema fails while doing adds or modifications, you’ll get an “Object Class Violation” error.

Comments on Notes and Domino 6 LDAP
Notes and Domino 6 takes LDAP a step further with some new enhancements. The first big thing is that LDAP is a mandatory task that starts by default on the administration server for the domain. Even if you don’t have the LDAP task in the ServerTasks line of the Notes.INI file, Domino sees that server as the Administration Server for the domain and automatically loads LDAP and writes it to the Notes.INI file. To find more information about ways to disable or make this unavailable, see the Release Notes for Notes and Domino 6 at http://www-10.lotus.com/ldd/notesua.nsf/find/rnrnext.
       Regarding enhancements, Lotus plans some performance improvements, including

· the ability to edit the ACL and pull names from a LDAP directory via the normal “add” dialogue rather than the way I described above
· improved migration capabilities via the LDAP Directory Upgrade Service
· Directory Assistance Failover capability to failover to third-party LDAP directories

But, of course, all of these features may not make it into Domino 6.
LDAP continues to grow as a protocol and in usage across applications. It can be quite a powerful tool for administrators to bring together disparate directories quickly, and it’s flexible enough to be modified to suit your enterprise’s needs. Domino has embraced LDAP and integrated it with the Domino server and Notes client, and you can expect more LDAP functionality in Domino as the technology continues to mature.

Chris Miller is director of messaging and collaboration at Connectria in St. Louis, Missouri. A PCLP in R5 and R4, Chris has been working with Domino administration since 1994 and is just finishing his Lotus Collaboration CLP. Some say he spends all his time behind a computer, but you can also find him on the soccer field — playing or coaching. You can reach him at chris@connectria.com.