CUSTOMIZING LDAP SETTINGS FOR COMMUNICATOR

Netscape Communicator 4.x
Last updated: 16 September 1997

INTRODUCTION

Netscape Communicator can interact with LDAP directories in three different ways:
  1. In the Address Book and Select Address dialog boxes (accessible from the mail composition window), users can enter one string of search criteria to search an LDAP directory for matching names.

  2. In the Search Directory dialog box, users can enter more complex query expressions to search an LDAP directory.

  3. Users can enter LDAP URLs (URLs beginning with the "ldap://" prefix) in Navigator (web browser) windows to search an LDAP directory.

This note describes ways in which MIS administrators can customize the settings that Communicator uses for these features.

NOTE: The intended audience for this note is MIS personnel who are familiar with X.500 and/or LDAP directories. Please read this note carefully before making changes. Making incorrect changes can disable your users' ability to search your directory.

HOW CUSTOMIZATION WORKS

You can customize the Communicator settings through JavaScript preferences. If you have configured an LDAP directory in Communicator, those settings have been saved into your prefs.js preferences file. The settings described in this note are accessible only through JavaScript preferences, since that is the mechanism for MIS administrators to distribute settings to all users in their enterprise. Note that settings are stored in the JavaScript preferences file only if they are not the default preference; Communicator stores the default values for preferences internally.

IMPORTANT: In Preview Release 5 (PR5), the syntax for these settings has changed again. In the current preview release, the preferences begin with ldap_1, instead of directories (as it was in PR3) or ldap (as it was in PR4). For example:

pref("ldap_1.directory1.attributes.mail", "mega_corp_email_address");

USING YOUR OWN ATTRIBUTE NAMES

By default, Netscape Communicator uses standard attribute names (which are described in the X.520 standard and in the LDAP protocol) when searching the directory. These include the following attributes: cn, givenname, sn, mail, telephonenumber, o, ou, l, and street.

If your directory schema uses different attribute names, you should specify your own attribute names in the prefs.js file to override Communicator's defaults. (Otherwise, Communicator's LDAP support may not work correctly with your directory.) For example, you might be using an attribute named mega_corp_email_address instead of the standard mail attribute for specifying user email addresses.

Changing the Attribute Used

To change the attributes used in directory searches, use the following syntax:

pref("ldap_1.directory1.attributes.<standard_attr>", "<your_attr>");

where <standard_attr> is the name of a standard attribute used by Communicator (such as mail), and <your_attr> is the name of your attribute that you want used in place of the standard attribute.

For example, if you want Communicator to use the attribute named mega_corp_email_address instead of mail when searching email addresses, include the following statement in the prefs.js file:

pref("ldap_1.directory1.attributes.mail", "mega_corp_email_address");

Changing the Displayed Name of the Attribute

You may also want to change the name of the attribute that is displayed to users (for example, you might want the name MegaCorp Mail ID to appear in the list of attribute, rather than Email). To change the displayed name of the attribute, use the following syntax:

pref("ldap_1.directory1.attributes.<standard_attr>", "<displayed_name>:<your_attr>");

where <displayed_name> is the name that you want displayed in the user interface. The colon (':') specifies to Communicator that the statement contains a name to use for display.

At most one colon may appear in an attribute name. If no colon appears, the entire string is interpreted as an attribute, and Communicator will use that name both in the user interface and in the actual filter expression for the search.

For example, if you want Communicator to display the name MegaCorp Mail ID in the user interface, include the following statement in the prefs.js file:

pref("ldap_1.directory1.attributes.mail", "MegaCorp Mail ID:mega_corp_email_address");

Using Multiple Attributes as Search Criteria

You may also want to specify more than one attribute when searching email addresses. For example, in some enterprises, users on different email systems have different attributes in the directory.

To specify additional attributes as search criteria, add the names of the attributes to then end of the statement in a comma-separated list. For example, if you want the search criteria applied to the mega_corp_email_address, mail, and email attributes, use the following syntax:

pref("ldap_1.directory1.attributes.mail", "MegaCorp Mail ID:mega_corp_email_address, mail, email");

The commas (','), which separate names after the colon, specify attribute names to be searched for email addresses. With the preference setting shown above, the filter string generated for "email address contains smith" would be:

(|(mega_corp_email_address=*smith*)(mail=*smith*)(email=*smith*))

Applicability and Default Settings

Applicability: Settings for standard attribute names apply to all three of the ways Communicator interacts with LDAP directories.

Default Settings: Although the prefs.js file does not contain actual JavaScript code for all the default settings, if these settings did appear, they would be express as follows:

pref("ldap_1.directory1.attributes.cn", "Name:cn");
pref("ldap_1.directory1.attributes.givenname", "First Name:givenname");
pref("ldap_1.directory1.attributes.sn", "Last Name:sn");
pref("ldap_1.directory1.attributes.mail", "Email address:mail");
pref("ldap_1.directory1.attributes.telephonenumber", "Phone Number:telephonenumber");
pref("ldap_1.directory1.attributes.o", "Organization:o");
pref("ldap_1.directory1.attributes.ou", "Organizational Unit:ou");
pref("ldap_1.directory1.attributes.l", "Locality:l");
pref("ldap_1.directory1.attributes.street", "Street Address:street");

ADDING MORE ATTRIBUTES

If you want to add attributes to the list used in the Search Directory dialog, you can define up to five additional attributes. Use the following syntax to add the attributes:

pref("ldap_1.directory1.attributes.custom<n>", "<addl_display_name>:<addl_attr>");

where <n> is a number of the additional attribute in the list (a number from 1 to 5), <addl_display_name> is the name that you want displayed in the user interface, and <addl_attr> is the name of the attribute that you want to add.

For example, to allow user to search on license plate numbers, you can add the standard carlicense attribute to the list by using the following statement:

pref("ldap_1.directory1.attributes.custom1", "License Plate:carlicense");

Note also that you can change any default attribute to one of your choosing. So if you prefer to allow users to search on car license numbers rather than street addresses, you can change the street entry in the list to use the carlicense attribute instead of street:

pref("ldap_1.directory1.street", "License Plate:carlicense");

Applicability and Default Settings

Applicability: Additional attribute names apply to all three of the ways Communicator interacts with LDAP directories.

Default Settings: Although the prefs.js file does not contain actual JavaScript code for all the default settings, if these settings did appear, they would be express as follows:

pref("ldap_1.directory1.custom1", "Custom 1:custom1");
pref("ldap_1.directory1.custom2", "Custom 2:custom2");
pref("ldap_1.directory1.custom3", "Custom 3:custom3");
pref("ldap_1.directory1.custom4", "Custom 4:custom4");
pref("ldap_1.directory1.custom5", "Custom 5:custom5");

SPECIFYING YOUR OWN FILTER STRINGS

In Communicator, you can also customize the filter strings used to find directory entries from the Address Book dialog box and from the Select Address dialog box in the Compose Window. By default, when you enter a name into the Address Book or Select Address dialog box, Communicator uses the entered name to generate a filter string for search criteria.

For example, if you enter the name "smith", Communicator generates the filter string (cn=*smith*).

If you want to customize the filter expressions to use different attributes, you can use the following syntax to provide your own filter expression:

pref("ldap_1.directory1.filter<n>.string", "<my_filter_expr>");

where <n> is a number of the attribute in the list that you are defining the filter for, and <my_filter_expr> is the filter expression that you want to use for that attribute.

For example, if you want to use the value entered under Name to find matching values in the givenname, sn, or cn attribute, use the following statement:

pref("ldap_1.directory1.filter1.string", "(|(givenname=%s)(sn=%s)(cn=%s))");

The symbol %s represents the text string typed by the user. This is the standard printf format that should be recognizable to C/C++ programmers.

If the user enters multiple words, Communicator separates the words and attempts to apply the filter expression to each word.

For example, if the filter expression is (cn=*%s*) if the user types "Bob Smith", Communicator will generate the filter string:

(&(cn=*Bob*)(cn=*Smith*))

To disable this behavior, you can set repeatFilterForWords to false. For example:

user_pref("ldap_1.directory1.repeatFilterForWords", false);

Applicability and Default Settings

Applicability: Custom filter strings only apply to the Address Book and Compose Window. The Search Directory dialog and LDAP URLs each contain a filter string as part of their normal operation.

Default Settings: Although the prefs.js file does not contain actual JavaScript code for all the default settings, if these settings did appear, they would be express as follows:

pref("ldap_1.directory1.filter1.string", "(cn=*%s*)");
pref("ldap_1.directory1.filter1.repeatFilterForWords",true);

SPECIFYING THE OBJECT CLASS TO SEARCH

By default, Communicator does not restrict searches to directory objects of any particular class. If you wish to search for particular object classes, or if you wish to exclude particular object classes from a search, you can encode that information in your filter string, as shown in these examples:

pref("ldap_1.directory1.filter", "(&(objectclass=Person)(cn=*%s*))");
pref("ldap_1.directory1.filter", "(&(!(objectclass=PayrollRecord))(mail=*%s*))");

Note that "not" expressions have two sets of parentheses, as specified in the RFC 1960 (the RFC that specifies filter expression syntax).

DEFAULT USE OF WILDCARDS

Communicator's default behavior in the Search Directory dialog box and the Address Book is to use wildcards in the filter expression (for example, (cn=*Bob*Smith*)) from the server. Although the Netscape Directory Server is capable of efficiently indexing strings for wildcard filters, other directory servers may not be as capable, which may result in searches that time out before completion.

In order to support these types of directory servers, Communicator allows you to disable wildcard searching by specifying this preference:

pref("ldap_1.directory1.efficientWildcards", false);

When this preference appears in the prefs.js file for a user, Communicator adapts by removing the "contains" and "doesn't contain" operators from the Search Directory dialog box. If you set efficientWildcards to false, you'll also want to change the default filter string, (cn=*%s*).

OTHER DIRECTORY RESOURCES

For more information on the LDAP protocol and LDAP directories, see the following resources:

Last Updated: Mon Dec 08 19:47:12 1997

Copyright © 1997 Netscape Communications Corporation