Configuring Directory VLV Browsing for Sun Java System Connector for Outlook

This article provides step-by-step instructions to set up the VLV browsing index for Directory Server 5.2 and 6 using the latest release of Sun Java System Connector for Outlook (7.2u1 - 125361-03). Directory server VLV browsing indexes are used by Connector for Outlook to improve the speed of resolving global address-book searches.

This document contains the following sections:

Using VLV settings in Connector for Outlook

The LDAP settings in the Connector for Outlook deployment configuration program directly impacts the required VLV browsing index configuration. Modifications in these settings must be reflected in changes to the appropriate VLV browsing directory index and directory ACI properties described later in this document.

VLV settings are stored in the LDAP Tab in the Connector for Outlook program as shown in the following figure.

Figure 1 Connector for Outlook Deployment Configuration Program, LDAP Tab

These instructions use the following mapping between the LDAP GAL (Global Address List) settings shown in Figure 1 and the requisite VLV index/ACI changes:

Other settings used in this article include:

To Use VLV Settings

1. If you wanted the Outlook GAL search to also provide results from other hosted-domain organisations, you could use the overall base for hosted domains, that is o=isp.
2. The security ramifications of the "Require authentication" tick-box are discussed in Providing Access to User Data.
3. This article assumes that the directory server has a single database back-end for user/group information (o=isp in this example). If multiple database back ends are used for the user/group tree (that is, one per hosted domain), then you need to add VLV browsing indexes will need to each appropriate back end.
4. The easiest mechanism to determine the database_backend setting is to refer to the dse.ldif directory configuration file located under the ds5_root_path/config/ directory for Directory Server 5.2, or the ds6_root_path/config/ directory for Directory Server 6.0, and search for nsslapd-suffix: user_group_base.
   
   (For Directory Server 6, the database_backend it is based on the user/group suffix supplied during the creation of the database instance and is the value of the cn: attribute, in this example it is "isp")
   dn: cn=isp,cn=ldbm database,cn=plugins,cn=config
   objectClass: top
   objectClass: extensibleObject
   objectClass: nsBackendInstance
   cn: isp
   creatorsName: cn=directory manager
   modifiersName: cn=directory manager
   entrydn: cn=isp,cn=ldbm database,cn=plugins,cn=config
   numSubordinates: 4
   nsslapd-suffix: o=isp
   nsslapd-cachesize: -1
   nsslapd-cachememsize: 10485760
   nsslapd-readonly: off
   nsslapd-require-index: off
   nsslapd-directory: /var/opt/SUNWdsee/dsins1/db/isp
   
   (for 5.2 the database_backend is userRoot by default)
   dn: cn=userRoot,cn=ldbm database,cn=plugins,cn=config
   objectClass: top
   objectClass: extensibleObject
   objectClass: nsBackendInstance
   cn: userRoot
   nsslapd-suffix: o=isp
   nsslapd-cachesize: -1
   nsslapd-cachememsize: 10485760
   nsslapd-readonly: off
   nsslapd-require-index: off
   nsslapd-directory: /opt/SUNWdir/slapd-directory/db/userRoot
   numSubordinates: 3

Creating a VLV Browsing Index

Important Note These steps must be performed on every directory server that will be used by the Outlook Connector. Directory server index configuration settings are not replicated.

The values used in this step are entirely dependant on the settings used earlier in the Outlook Connector deployment configuration and the site settings for user/group organisation base etc.

If an index has not been created, searches will take considerable time (minutes) for large environments and the Outlook will appears to 'hang' when searching for address information, attempting to subscribe to a calendar etc. If the time taken to perform the search is longer then the configured search timeout (1 minute by default), no results will seen by the end-user.

In the directory server logs you will see VLV searches returning after a period of time and a "notes=U" in the result line -- indicating the lack of an index.

An example of such a search is shown below:

[04/Dec/2007:08:59:07 -0800] conn=2500737 op=1 msgId=2 - SRCH base="o=aus.sun.com,o=isp" scope=2 filter="(&(mail=*)(cn=*))" attrs="cn mail uid objectClass"
[04/Dec/2007:09:00:07 -0800] conn=2500737 op=1 msgId=2 -  SORT cn (12345)
[04/Dec/2007:09:00:07 -0800] conn=2500737 op=1 msgId=2 -  VLV 1:1:1:0 0:0 (0)
[04/Dec/2007:09:00:07 -0800] conn=2500737 op=1 msgId=2 - RESULT err=12 tag=101 nentries=0 etime=60 notes=U
[04/Dec/2007:09:04:07 -0800] conn=2500737 op=10 msgId=11 - ABANDON targetop=9 msgid=10 nentries=0 etime=60

To Apply the VLV Browsing Index Settings

The following ldap modifications will add the required directory settings to allow for the VLV index creation.

ldapmodify -h directory_server_hostname -p directory_server_port -D "cn=Directory Manager"
dn: cn=Browsing database_backend,cn=database_backend,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectClass: top
objectClass: vlvSearch
cn: Browsing database_backend
vlvbase: organisation_base
vlvscope: 2
vlvfilter: vlv_search_filter
aci: (targetattr="*")(version 3.0; acl "VLV for Anonymous";
 allow (read,search,compare) userdn="ldap:///anyone";)

dn: cn=Sort by vlv_sort_attribute,cn=Browsing database_backend,cn=database_backend,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectClass: top
objectClass: vlvIndex
cn: Sort by vlv_sort_attribute
vlvSort: vlv_sort_attribute

So using the example settings listed earlier the values would be:

ldapmodify -h directory.aus.sun.com -p 389 -D "cn=Directory Manager"
dn: cn=Browsing isp,cn=isp,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectClass: top
objectClass: vlvSearch
cn: Browsing isp
vlvbase: o=aus.sun.com,o=isp
vlvscope: 2
vlvfilter: (&(mail=*)(cn=*))
aci: (targetattr="*")(version 3.0; acl "VLV for Anonymous";
 allow (read,search,compare) userdn="ldap:///anyone";)

dn: cn=Sort by cn,cn=Browsing isp,cn=isp,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectClass: top
objectClass: vlvIndex
cn: Sort by cn
vlvSort: cn

To Generate the VLV Browsing Index

These steps which propagate the index with data, require that the directory server be shut-down and should therefore be performed during a scheduled change window.

Directory Server 6 instructions

cd /opt/SUNWdsee/ds6/bin
./dsadm stop ds6_root_path
./dsadm reindex -l -t "Sort by vlv_sort_attribute" ds6_root_path "user_group_base"
./dsadm start ds6_root_path

So using the example settings listed earlier the values would be:

cd /opt/SUNWdsee/ds6/bin
./dsadm stop /var/opt/SUNWdsee/dsins1/
./dsadm reindex -l -t "Sort by cn" /var/opt/SUNWdsee/dsins1/ "o=isp"
./dsadm start /var/opt/SUNWdsee/dsins1/

Directory Server 5.2 instructions

cd ds5_root_path
./stop-slapd
./vlvindex -n database_backend -T "Sort by vlv_sort_attribute"
./start-slapd

So using the example settings listed earlier (note that by default database_backend is userRoot for 5.2):

cd /opt/SUNWdir/slapd-directory
./stop-slapd
./vlvindex -n userRoot -T "Sort by cn"
./start-slapd

Providing Access to User Data

Careful consideration must made when determining the mechanism used to allow access to user and group data in the organisations directory. Organisations are now increasingly under pressure to reduce the amount of private data that non-authorised entities can access. The Sun Outlook Connector on the other-hand must access user data for correct operation of the GAL and other functionality (e.g. sharing calendars).

Directory server installations by default block access to user data which therefore means Access Control changes are required for the Outlook Connector to provide the best end-user experience.

To Determine the Appropriate ACI Mechanism

The following is a non-exhaustive list from most-to-least preferred from a security perspective of the possible approaches to granting access to user data. Granting access is required to allow the Outlook Connector GAL search to correctly function.

• Access by authenticated users in same domain to limited attributes
• Access by authenticated users in same domain to all attributes (except userpassword)
• Access by authenticated users in any domain to limited attributes
• Access by authenticated users in any domain to all attributes (except userpassword)
• Anonymous access to limited attributes
• Anonymous access to all attributes (except userpassword)

For each option you could optionally apply an IP based restrictions i.e. restrict access to clients which are running Outlook Connector software on hosts within a specific IP range. Details on additional ACI mechanisms can be found here: http://docs.sun.com/source/816-6698-10/aci.html#14960

Please also note that each additional ACI's can have the cost of additional processing by the directory server.

The list of 'limited attributes' was compiled based on reverse-engineering a search by an Outlook Connector installation on MS Outlook 2007. The values may change in the future or could be reduced if not appropriate for your environment.

To Configure Authenticated User Access

This is the most desirable approach as it restricts access to only those users who provide the correct authentication details. This has the advantage of being very granular and will allow the administrator to identify which user is attempting to make a search which can be useful for debugging, throttling etc.

If using this approach please also consider the use of SSL encryption for Directory Server access. If you have not configured the Outlook Connector plugin to contact the LDAP server on an SSL port, Outlook Connector will send user login details in clear-text when binding to the directory.

a) Configure the Outlook Connector plugin

In the LDAP tab of the Sun Outlook Connector Deployment Configuration software, enable the "Require Authentication" option.
In the same tab, set the User DN: pattern to an appropriate value e.g.

uid=%s,ou=People,o=aus.sun.com,o=isp

This will result in the Outlook Connector binding as the login user (the %s will be substituted with the login username).

b) Enable user access to user/group details

To determine the most appropriate ACI for your organisation you should consider who is given access to what.

In this case the whois either any authenticated user (so any user in the directory), which has a special ACI representation of "ldap:///all", or any user at a specific domain level which can be represented as a DN wildcard match e.g. "ldap:///uid=*,ou=people,o=aus.sun.com,o=isp" You will notice that the DN wildcard match is very similar to the value used in step (a) above.

The what is controlled by where in the directory tree you add the ACI, for example at the base of the organisation or at the base of a hosted domain. This is referred to as the base_for_aciin steps below. The user/group attributes you choose to return will also determine what information is provided back to the client, Outlook Connector in this case.

In a hosted domain environment for example you may want to prevent users from one domain accessing another domain. In this case you would apply the access control at the domain level rather then at the organisation level and allow results to be returned for users who's DN's contain the hosted domain LDAP base path.

Example 1: Authenticated access by users in same domain to limited attributes
aci: (targetattr = "cn || displayName || givenName || sn || initials || uid || departmentNumber ||
 title || homePhone || mail || manager || mobile || company || pager || secretary || description ||
 facsimileTelephoneNumber || l || physicalDeliveryOfficeName || postalCode || st || street || c ||
 telephoneNumber || mailAlternateAddress || isMemberOf || objectClass")
 (version 3.0;acl "Authenticated user access at domain-level";
 allow (read,compare,search)(userdn = "ldap:///uid=*,ou=people,o=aus.sun.com,o=isp");)

Example 2: Authenticated access by users in same domain to all attributes (except userpassword)
aci: (targetattr != "userPassword")(version 3.0;acl "Authenticated user access at domain-level";
 allow (read,compare,search)(userdn = "ldap:///uid=*,ou=people,o=aus.sun.com,o=isp");)

Example 3: Authenticated access by users in any domain to limited attributes
aci: (targetattr = "cn || displayName || givenName || sn || initials || uid || departmentNumber ||
 title || homePhone || mail || manager || mobile || company || pager || secretary || description ||
 facsimileTelephoneNumber || l || physicalDeliveryOfficeName || postalCode || st || street || c ||
 telephoneNumber || mailAlternateAddress || isMemberOf || objectClass")
 (version 3.0;acl "Authenticated user access"; allow (read,compare,search)(userdn = "ldap:///all");)

Example 4: Authenticated access by users in any domain to all attributes (except userpassword)
aci: (targetattr != "userPassword")(version 3.0;acl "Authenticated user access";
 allow (read,compare,search)(userdn = "ldap:///all");)

Once you have determined the most appropriate ACI settings, use the following command to apply the rule to the directory:

ldapmodify -h <directory server host> -p <directory server port> -D "cn=Directory manager"
dn: base_for_aci
changetype: modify
add: aci
aci: user_data_aci

e.g.

ldapmodify -h directory.aus.sun.com -p 389 -D "cn=Directory manager"
dn: o=aus.sun.com,o=isp
changetype: modify
add: aci
aci: (targetattr != "userPassword")(version 3.0;acl "Authenticated user access at domain-level";
  allow (read,compare,search)(userdn = "ldap:///uid=*,ou=people,o=aus.sun.com,o=isp");)

c) Testing the settings

To test that the setting is working correctly do the following:

ldapsearch -h directory_server_hostname -p directory_server_port -D user_dn -b user_group_base objectclass=inetmailuser dn uid mail

e.g.

ldapsearch -h directory.aus.sun.com -p 389 -D "uid=someuser,ou=people,o=aus.sun.com,o=isp" -b o=isp objectclass=inetmailuser dn uid mail

This should return a list of uid's, mail addresses and dn's of the users and groups in the organisation or domain of the user 'someuser' depending on the ACI that was added in step (b).

To Configure Anonymous Access

Granting access to data for connections that bind anonymously is not-desirable as it opens up the potential for the data to be accessed by anybody e.g. undesirable elements such as spammers could potentially get access to all the mail addresses of an organisation. At a minimum any anonymous access should be restricted on an IP basis e.g. to just IP addresses used by the organisation's servers and clients.

If your organisation restricts access to the directory servers through some other means (e.g. network perimeter firewalls which block access to port 389/636), you could use the following rules to allow access to data.

Example 1: Anonymous access to limited attributes
aci: (targetattr = "cn || displayName || givenName || sn || initials || uid || departmentNumber ||
 title || homePhone || mail || manager || mobile || company || pager || secretary || description ||
 facsimileTelephoneNumber || l || physicalDeliveryOfficeName || postalCode || st || street || c ||
 telephoneNumber || mailAlternateAddress || isMemberOf || objectClass")
 (version 3.0;acl "Anonymous access";allow (read,compare,search)(userdn = "ldap:///anyone");)

Example 2: Anonymous access to all attributes (except userpassword)
aci: (targetattr != "userPassword")(version 3.0;acl "Anonymous access";
 allow (read,compare,search)(userdn = "ldap:///anyone");)

a) Configure the Outlook Connector plug-in

In the LDAP tab of the Sun Outlook Connector Deployment Configuration software, disabled the "Require Authentication" option. This will result in Outlook connector using the anonymous bind functionality.

b) Grant anonymous access to VLV browsing indexes

The following grants anonymous VLV browsing index request access which by default is denied to non-authenticated bind sessions.

ldapmodify -h directory_server_hostname -p directory_server_port -D "cn=Directory Manager"
dn: oid=2.16.840.1.113730.3.4.9,cn=features,cn=config
changetype: modify
add: aci
aci: (targetattr !="aci")(version 3.0; acl "VLV Request Control";
 allow (compare,read,search) userdn = "ldap:///anyone";)

e.g.

ldapmodify -h directory.aus.sun.com -p 389 -D "cn=Directory Manager"
dn: oid=2.16.840.1.113730.3.4.9,cn=features,cn=config
changetype: modify
add: aci
aci: (targetattr !="aci")(version 3.0; acl "VLV Request Control";
 allow (compare,read,search) userdn = "ldap:///anyone";)

If you have not successfully added this ACI, the end-user will see the error "The action cannot be completed" in Outlook 2007 and an error (err=50) will be returned in the directory access logs when attempting to access the VLV control e.g.

[06/Dec/2007:12:48:54 +1100] conn=168 op=6 msgId=7 - SRCH base="o=aus.sun.com,o=isp" scope=2 filter="(&(mail=*)(cn=*))" attrs="uid mail cn title company 
telephoneNumber physicalDeliveryOfficeName objectClass"
[06/Dec/2007:12:48:54 +1100] conn=168 op=6 msgId=7 - RESULT err=50 tag=101 nentries=0 etime=0, VLV Control

c) Enable anonymous access to user & group details

The following step grants anonymous access to user/group attributes.

ldapmodify -h <directory server host> -p <directory server port> -D "cn=Directory manager"
dn: base_for_aci
changetype: modify
add: aci
aci: user_data_aci

e.g.

ldapmodify -h directory.aus.sun.com -p 389 -D "cn=Directory manager"
dn: o=aus.sun.com,o=isp
changetype: modify
add: aci
aci: (targetattr != "userPassword")(version 3.0;acl "Anonymous access";
 allow (read,compare,search)(userdn = "ldap:///anyone");)

If you have not successfully added this entry, you will get no results returned from your search (nentries=0) e.g.

[06/Dec/2007:13:10:39 +1100] conn=197 op=1 msgId=10 - SRCH base="o=aus.sun.com,o=isp" scope=2 filter="(&(mail=*)(cn=*))" attrs="uid mail cn title company 
telephoneNumber physicalDeliveryOfficeName objectClass"
[06/Dec/2007:13:10:39 +1100] conn=197 op=1 msgId=10 - SORT cn (10)
[06/Dec/2007:13:10:39 +1100] conn=197 op=1 msgId=10 - VLV 0:9:0:0 1:10 (0)
[06/Dec/2007:13:10:39 +1100] conn=197 op=1 msgId=10 - RESULT err=0 tag=101 nentries=0 etime=0

d) Testing the settings

To test that the ACI setting is working correctly do the following:

ldapsearch -h directory_server_hostname -p directory_server_port -b user_group_base objectclass=inetmailuser dn uid mail

e.g.

ldapsearch -h directory.aus.sun.com -p 389 -b o=isp objectclass=inetmailuser dn uid mail

This should return a list of uid's, mail addresses and dn's of users in your organisation.

For More Information

• Managing browsing indexes in Directory 6.0
• Configuring and Enabling VLV indexes in Directory Server 5.2
• Directory server ACI information