E-Pro: Troubleshooting LDAP in Domino
Tags :E-Pro Articles
While taking a brief, but unscheduled, nap in the weekly staff meeting, you were just delegated the new project and were unable to object. Your assigned mission: Integrate all the mail system, customer and business partner directories so the sales staff and customer service representatives can easily retrieve email addresses and other pertinent information. Also, to allow those same customers and business partners to search your directory. Of course everyone uses a different mail system and data storage format just to make the project that much easier. Everyone cheers for you as you exit the meeting in horror.
But you have no fear because your enterprise runs on Domino, so you can easily let others search authenticated or anonymously against your directory with the capabilities of LDAP. You can even search their directories if they allow LDAP.
The basics of LDAP (Lightweight Directory Access Protocol) are quite simple, yet with any protocol and software there can be areas of mishap and necessary troubleshooting when establishing a LDAP architecture.
A Very Brief LDAP Background
LDAP, a communication protocol over TCP/IP, was designed as a lightweight option to DAP (Directory Access Protocol) to 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 distinguished name. The communication between the server and client on X.500 directory searches is defined in a format by this protocol. When a client opens a session with an LDAP server it is called binding. The client then searches based on anonymous rights, or authenticate (if offered) to gain more privileges.
Of course, people always say that they are implementing a LDAP Directory. The true meaning would be a LDAP accessible directory, but I will let that one go for the sake of terminology. A 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 not reachable or interoperable with the others. LDAP evolved to meet that need and vendors have embraced it. LDAP is gaining wide acceptance across numerous software packages as a way to offer that directory integration that you were just tasked with. Even Sun has recently put LDAP as its directory infrastructure in the new Solaris 9.
Domino LDAP Security
Before you open your Domino directory to LDAP searches you should also review what fields you are making available for security purposes and what policies will be set in relation to directory updates via LDAP. While opening your directory to the public for searches of email addresses or phone numbers might be beneficial, information that is enabled by default, such as Location, might not be for security reasons. You can configure the fields available for anonymous access in the Server Configuration document found in the Domino Directory. (Figure 1)
Domino integrates the security policy of the ACL into LDAP to provide authentication to gain more access to information via LDAP or more permission on management of the directory. You can allow the users to update entries via LDAP by setting at least Editor access, or Author access with additional roles, in the Access Control List (ACL) of the Domino Directory. You must also set the field "Allow LDAP users write access" in the Server Configuration document . By selecting “Yes” on this field, authenticated LDAP users can make adds, deletes and modifications based on the roles and rights in the ACL.
If you do not allow anonymous access and require all users to provide a name-and-password to authenticate, you have options in forcing the user to provide their user or short name or the more specific fully qualified distinguished name. By default, Domino LDAP uses the user or short name option. The only way to enable the more specific option, referring to RFCs 2251 through 2254, is to add a line to the notes.ini of
LDAP_Strict_RFC_Adherence=1
Once this notes.ini setting is put in place and the LDAP server task restarted on Domino, the user will then only authenticate using their hierarchical name. For example Bob Jones/Sales/Corp will be allowed but Bob Jones or bjones will not.
Authentication options for allowing anonymous access is set in the Domino Server document under Ports, Internet Ports, and Directory tabs. From there, as long as “TCP/IP port status” is Enabled, you have the ability to answer Yes and No to allowing Name & Password and Anonymous access from LDAP clients. If you do allow Anonymous, I cover how to set which fields are available to Anonymous access below in the section The Capabilities of LDAP in Domino.
Loading LDAP on Domino the First Time
Lotus began offering and utilizing the capabilities of LDAP back in version 4.6, but I will be addressing R5 only. Lotus is moving closer to the full release of Notes and Domino 6 in late 2002 and Domino 4.6x will not be supported in the near future.
Let me address one configuration item that, honestly, even confused me at first in how Domino offered configuration of LDAP. The advanced LDAP settings (timeout values, anonymously queriable fields, etc.) are configured 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. This is a common area of confusion and misconception when establishing configurations for LDAP.
Basically, there is one default document for your domain that controls LDAP for all servers. You then specify LDAP settings for all the different servers in the domain in one general configuration. So make sure you do not create a specific configuration document for the server running LDAP or you will lose the LDAP tab. While Lotus designed this to ease administration through one global document, it would be nice sometimes to have different LDAP settings for different servers as some might be inside the firewall for company staff, and others in the DMZ for business partners and customers.
A common misconception on the timeout setting on the Server Configuration for LDAP is that connections will be dropped after the timeout specified. This timeout is for LDAP searches only and not actual connections to the LDAP server.
The first time you load LDAP on your Domino R5 server is as simple as typing load ldap on the server console. This will start the LDAP server task and allow access to LDAP clients to make inquiries against your Domino directory.
One immediate error that may occur 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 “Disabled” in the server document and is easily remedied by editing the document in the Domino directory that will be running the LDAP task. Navigate to the tab for Ports, Internet Ports, and Directory tabs, and "TCP/IP port status" field. Before loading LDAP just verify that this field is set to “Enable”, unless you will only be utilizing LDAP over a SSL connection or SASL (Simple Authentication and Security Layer), as it is called.
There are a few items to be familiar with if choosing SASL in your LDAP solution. No protocol other than LDAP has the ability to utilize SASL. Domino integrates SASL into the LDAP server. Administratively there is nothing else you need to do to enable SASL outside of going to the same server document tabs as above and enabling the SSL port for LDAP. The connecting LDAP client must also support SASL of course, and when it connects, the Domino server will automatically initiate an SASL session. To find more information about SASL, consult RFCs 2222 and 2444 at http://www.rfc-editor.org/rfc.html . SASL is still evolving so expect modifications also as time goes on.
Performance Enhancement Opportunities
Lotus offers one main option to enhance performance; create a full-text index of the Domino Directory on the server that runs LDAP. This is unless you are only looking up names of users. Since Domino uses the ($users) view first, full-text indexing would not be necessary and would use resources maintaining the full-text index.
The Domino LDAP task, by default, will also allow searches to take as long as necessary when a query is made from a LDAP client. If you see slow performance, or over time as usage grows performance starts to slow, take the opportunity to 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 a LDAP client has the ability to control these settings also, the one with the lower setting takes precedence.
One other area that affects performance is the setting you configure for search results returned and the number of wildcards allowed. The configuration allows you to specify the number of characters that a LDAP client must place before the wildcard search (*) in the request. The default for the wildcard search is one character. If performance is slow and you are aware that LDAP clients are performing searches, try increasing this value to 2 as the minimum amount necessary before the wildcard. All this does is require the LDAP client to make a more specific search so the lookup also returns fewer entries to the client.
Some caveats do exist. If the LDAP client attempts to use a wildcard as the first character, as in *ones, then Domino will drop the first wildcard (unless "Minimum characters for wildcard search" is set to 0) and proceed 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 characters required for a search was set to 2. Domino ignores the first wildcard (*), then rejects the entire search since the user did not specify 2 characters and the other wildcard (*) was at the end. Also, the “Minimum characters for wildcard search” will not apply to the LDAP client search if the only character sent in the search is a wildcard. Basically, that type of search is used to see if a specific LDAP attribute exists. You can still set the “Maximum number of entries returned” configuration setting if you are concerned about performance hits from that type of search.
The Capabilities of LDAP in Domino
Overall, the directories in Domino are not updated as often as they are searched or read. I have heard quite a few administrators say that no one even reads their Domino directory and they do not 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 will search the Domino Directory in a certain order looking for the information that has been requested. 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 spouse's name, the Domino LDAP task goes directly to the full text index, or if there is not a full text Index, to the ($PeopleGroupHier) view.
I recently had a client ask to synchronize their Domino Directory by pulling updates from another existing LDAP accessible directory they already had available. Domino does not allow you to pull updates from another directory via LDAP, currently. I know IBM has a utility to allow you to do this with existing Domino servers. If you are choosing to make all initial changes in Domino and then let some 3rd party LDAP directory connect and update itself from Domino, this is possible. You will have to check with the 3rd party vendor to verify they have that capability.
Domino R5 also has the ability to export the Domino Directory into LDIF (Lightweight Data Interchange Format). LDIF is the RFC-compliant format that LDAP servers and clients adhere to in building their LDAP schemas. You can retrieve the exported file through a simple command line from the Notes client:
ldapsearch -h LDAPservername objectclass = * > filename.txt
The specified output file can then be imported to another LDAP server. I will cover move about LDAP schemas in the next section.
Also, not all fields are available for searching through LDAP. Resource documents are one of those fields. For a complete list of fields that are excluded from LDAP accessibility see technote #190495. Resources are an object class of a database, which excludes them. When configuring LDAP fields in the Server Configuration document, some of these excluded fields show as a choice, but they are not valid.
Groups in a Domino Directory serving LDAP requests are also handled differently if your groups contain spaces. When a LDAP client makes a request for the email address of a group that is stored with a space, the LDAP server will return underscores where the spaces were. This is since spaces are not valid SMTP characters in Internet addresses. Of course mail will then fail to this address since it is not valid in the Domino Directory.
If you are utilizing LDAP queries for web authentication on your Domino server, you must enter names differently in ACL’s for users to authenticate correctly. LDAP will retrieve the name in full canonical format. A returned result will look like “CN=Bob Jones/OU=Sales/O=Corporation”. This is the exact name you will then list in the ACL for a user authenticating through a Domino LDAP lookup.
You can correct this be 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.
On the Notes client side, another request I’ve had from a client was to be able 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 through LDAP. Lotus has now documented this as an enhancement request. This also affects type ahead addressing from the Notes client. You can not get type ahead features to work when addressing a mail message currently in R5. You will have to hit F9, which invokes the namelookup, to get an address choice list to pop up.
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) will not return that group. An example is if 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 hierarchical. Reference technote #180188 for more information on this topic.
Working with the Domino LDAP Schema
A schema is a map of LDAP attributes to the actual record stored in the directory. It is used by any software that provides a LDAP accessible directory. Domino R5 has 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 is possible to get errors related to loading the LDAP schema. One reason that this error would occur is if one of the LDAP forms was corrupted or was customized incorrectly. The LDAP task would be unable to reconcile the schema. This, in turn, would show the LDAP task closing immediately after loading it. For this type of error, there is a notes.ini file that can be utilized to show the form or even directory that is 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.
There are a couple of options to retrieve information on the schema that Domino is currently providing on your Domino LDAP server. The most user-friendly selection is the Domino LDAP Schema database (SCHEMA50.NSF). That database will be 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 will not function. You are able to 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 will also update this database, or create it for the first time, after the schema is loaded into memory. The Domino LDAP Schema database will provide quite a bit of information on attributes. I would suggest opening and becoming familiar with this database after loading LDAP. You are even able to do full-text searches in the database by default, after the full-text is created of course.
You may also use the ldapsearch utility mentioned earlier with some other options or any LDAP V-3 complaint client. A sample command to retrieve the directory schema would be:
ldapsearch -h hostname -b "cn=schema" -s base "(objectclass=subschema)">filename.txt
This will create an output for you to view in text format. While not as user-friendly, this type of export is importable into other LDAP directories.
It is also possible to extend the Domino schema by adding attributes and object classes to the schema. You actually accomplish this by using Domino Designer and creating new or modifying existing subforms and forms into the Domino Directory. Anytime you extend the schema, you can enter “tell ldap reloadschema” into 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 does not perform schema checking by default. It is a step you must manually enable by editing the notes.ini file with the line:
LDAP_Enforce_Schema=1
The Domino LDAP server task must then be restarted for this to take effect. Once enabled, LDAP will only take modifications that conform to the directory schema already. 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 will receive an error of “Object Class Violation”.
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 do not have the LDAP task in the ServerTasks line of the notes.ini, Domino will see that server as the Administration Server for the domain and automatically load LDAP and write it to the notes.ini. There are ways to disable or make this unavailable, but I will direct you to the Release Notes for Notes and Domino 6 to gather more information on that.
In reference to enhancements, there are of course performance improvements, but the normal caveats apply that certain things may not make it into the product or might be delayed, but a short list is:
· The ability to edit the ACL through the normal “add” dialogue and pull names from a LDAP directory instead of the way I described above.
· Improved migration capabilities through the LDAP Directory Upgrade Service.
· Directory Assistance Failover will now include the ability to failover to 3rd party LDAP directories.
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, as long as you keep in mind that it is also flexible enough to be modified to suit your enterprise needs. Domino has embraced this and continues to mature in the integration through the Domino server and Notes client. I hope you found this helpful as a starting guide to your deployment of LDAP in Domino. This should also cure you sleeping through meetings.
blog comments powered by Disqus
On Monday, September 2nd, 2002 by Chris Miller
