Chapter 13 Working with LDAP Controls

This chapter explains how LDAP controls work and how to use the LDAP controls that are supported by the Netscape Directory Server.

• "How LDAP Controls Work"
• "Using Controls in the LDAP Java Classes"
• "Determining the Controls Supported By the Server"
• "Using the Server-Side Sorting Control"
• "Using the Persistent Search Control"
• "Using the Entry Change Notification Control"
• "Using the Virtual List View Control"
• "Using the Manage DSA IT Control"
• "Using Password Policy Controls"
• "Using the Proxied Authorization Control"

• A unique object identifier (OID)
• An indication of whether or not the control is critical to the operation
• Optional data related to the control (for example, for the server-side sorting control, the attributes used for sorting search results)

• If the server supports this control and if the control is appropriate to the operation, the server should make use of the control when performing the operation.
• If the server does not support the control type or if the control is not appropriate, the server should do one of the following:

• If the control is marked as critical to the operation, the server should not perform the operation and should send an "unavailable critical extension" result code. When receiving this result code, your client throws an LDAPException with the result code LDAPException.UNAVAILABLE_CRITICAL_EXTENSION.
• If the control is marked as not critical to the operation, the server should ignore the control and should proceed to perform the operation.

• Server controls can be included in requests sent by clients and in responses sent by servers.
• Client controls affect the behavior of the LDAP Java classes only and are never sent to the server. (At this point in time, no client controls are supported in the Netscape Directory SDK for Java.)

1. Invoke the getSearchConstraints method of the LDAPConnection object to get a clone of LDAPSearchConstraints for this connection.
2. Invoke the setServerControls method of the cloned constraints object, passing in the LDAPControl object that represents the control you want to include.
3. Invoke the appropriate method to perform the LDAP operation, passing in the constraints object. For example, if you are performing a search, invoke the search method and pass the search constraints as an argument.

...

import netscape.ldap.*;

import netscape.ldap.controls.*;

import java.util.*;

...

public class ListCtrl {

   public static void main( String[] args ) {



      /* Hashtable mapping OIDs of known controls to descriptions of 

         each control. */

      Hashtable knownControls = new Hashtable();

      knownControls.put( LDAPSortControl.SORTREQUEST, 

         "Sort control" );

      knownControls.put( LDAPControl.MANAGEDSAIT, 

         "ManageDsaIT control" );

      knownControls.put( LDAPPersistSearchControl.PERSISTENTSEARCH, 

         "Persistent Search control" );

      knownControls.put( LDAPControl.PWEXPIRED, 

         "Password Expiration Notification control" );

      knownControls.put( LDAPControl.PWEXPIRING, 

         "Password Expiration Warning control" );

      knownControls.put( LDAPVirtualListControl.VIRTUALLIST, 

         "Virtual List View control" );

      knownControls.put( LDAPProxiedAuthControl.PROXIEDAUTHREQUEST, 

         "Proxied Authorization control" );



      LDAPConnection ld = new LDAPConnection();

      String hostname = "localhost";

      int portnumber = LDAPv2.DEFAULT_PORT;

      try {



         /* Connect and authenticate to server */

         ld.connect( 3, hostname, portnumber );



         /* The list of supported controls can be retrieved by

            getting the root DSE.  To get the root DSE, you need

            to do a search where:

            - The scope is SCOPE_BASE

            - The base is ""

            - The search filter is "(objectclass=*)"

            The values of the supportedControl attribute of the

            resulting entry are the OIDs of the supported controls. */

         int MY_SCOPE = LDAPv2.SCOPE_BASE;

         String MY_FILTER = "(objectclass=*)";

         String MY_SEARCHBASE = "";

         String getAttrs[] = { "supportedControl" };

         LDAPSearchResults res = ld.search( MY_SEARCHBASE,

            MY_SCOPE, MY_FILTER, getAttrs, false );



         /* There should only be one entry found. */



         /* Get the attributes of this entry. */

         LDAPEntry DSE = (LDAPEntry)res.nextElement();

         LDAPAttributeSet findAttrs = DSE.getAttributeSet();

         Enumeration enumAttrs = findAttrs.getAttributes();



         /* Print each attribute returned 

            (this should only be the supportedControl attribute) */

         while ( enumAttrs.hasMoreElements() ) {

            LDAPAttribute anAttr = 

               (LDAPAttribute)enumAttrs.nextElement();

            String attrName = anAttr.getName();

            System.out.println( attrName );



            /* Get the values of this attribute. */

            Enumeration enumVals = anAttr.getStringValues();

            if ( enumVals == null ) {

               System.out.println( "\tNo values." );

               continue;

            }

            while ( enumVals.hasMoreElements() ) {

               String aVal = ( String )enumVals.nextElement();



               /* Each value should be the OID of a control. Look up the 

                  description corresponding to the OID. */

               String aDesc = ( String )knownControls.get( aVal );

               if ( aDesc != null ) {

                  System.out.println( "\t" + aDesc+ " (" + aVal + ")" );

               } else {

                  System.out.println( "\t" + aVal );

               }

            }

         }

      }

      catch( LDAPException e ) {

            System.out.println( "Error: " + e.toString() );

      }

      try {

         ld.disconnect();

      }

      catch( LDAPException e ) {

          System.exit(1);

      }

      System.exit(0);

   }

}

...

This section covers the following topics:

• "Specifying the Sort Order"
• "Creating the Control"
• "Performing the Search"
• "Interpreting the Results"
• "Known Problems with Server Sorting"
• "Example of Using the Server-Sorting Control"

[-]<attrname>[:<matchingruleoid>]

"-givenname"

LDAPSortKey sortByFirstNameReverse = new LDAPSortKey( "-givenname" );

...

LDAPSortKey sortByLastName = new LDAPSortKey( "sn" );

LDAPSortKey sortByFirstName = new LDAPSortKey( "givenname" );

LDAPSortKey[] sortOrder = { sortByLastName, sortByFirstName };

...

• For attributes that have multiple values, the Netscape Directory Server 3.x will use the "highest" value when sorting.

For example, suppose you choose to sort by the ou attribute. If an entry has "Accounting" and "People" as values of the ou attribute, the server will use "People" when sorting this entry.

On the other hand, if the values are "People" and "Product Development", the server will use "Product Development" when sorting the entry.

• If an entry does not contain the attribute used for sorting, the Netscape Directory Server 3.x sorts that entry before other entries that do contain the attribute.

For example, suppose the entry for Barbara Jensen does not contain the ou attribute and the entry for Kurt Jensen does contain the ou attribute. If the server is sorting by the ou attribute, Barbara Jensen's entry will come before Kurt Jensen's entry in the sorted results.

LDAPSortKey sortOrder = new LDAPSortKey( "-givenname" );

LDAPSortControl sortCtrl = new LDAPSortControl( sortOrder, true );

1. Get a clone of LDAPSearchConstraints for the current connection by invoking the getSearchConstraints method of the LDAPConnection object.
2. Invoke the setServerControls method for the copied LDAPSearchConstraints object, and pass in the LDAPSortControl object that you have constructed.
3. Invoke the search method of the LDAPConnection object, passing in the LDAPSearchConstraints object.

The server returns a result for the search operation and a response control. The response control indicates the success or failure of the sorting.

1. Invoke the getResponseControls method of the LDAPSearchResults object to retrieve any controls sent back by the server in response to the search.

Response controls are passed back as an array of LDAPControl objects.

1. Examine the type of each returned control. If a control is an instance of LDAPSortControl, you can read the result code for the sorting operation using the getResultCode method.

If the sorting operation failed, the server may also return the name of the attribute that caused the failure. You can read the name of this attribute with the getFailedAttribute method.

• The server does not sort entries if the search filter consists of unindexed attributes.

When processing a search request, the server generates a list of potential candidates from the indexes, sorts the candidate list, then compares each candidate against the search filter.

If no indexes are applicable to the search, the candidate list consists of all entries. If the candidate lists consists of all entries, the server does not sort the list and instead sends back an LDAP_UNWILLING_TO_PERFORM result code.

For example, suppose your search filter is "l=Sunnyvale". Since the "l" attribute (the "location" attribute) is not indexed by default, the server cannot use any indexes to narrow down the list of potential candidates, and all entries are considered candidates. If you attempt to sort by any attribute, the server will refuse to sort the entries.

• The server does not sort entries if you bind as the root DN and specify no time limit.

Normally, if you bind as the root DN and specify no time limit, the server allows you an infinite time limit. As the server sorts the list of candidate entries during a search, the server checks to determine if the time limit has been exceeded. However, the server incorrectly calculates the amount of time allowed, so larger sets of candidates will not be sorted.

...

import netscape.ldap.*;

import netscape.ldap.controls.*;

import java.util.*;

...

public class SrchSort {

   public static void main( String[] args ) {

      LDAPConnection ld = new LDAPConnection();

      String hostname = "localhost";

      int portnumber = LDAPv2.DEFAULT_PORT;

      int status = -1;



      try {

         /* Connect to server */

         ld.connect( 3, hostname, portnumber, "", "" );



         /* Search for last names that start with "Wa". */

         String MY_FILTER = "sn=Wa*";

         String MY_BASE = "o=Airius.com";

         String[] attrs = { "sn", "givenname" };



         /* Create sort keys that specify the sort order. */

         LDAPSortKey sortByLastName = new LDAPSortKey( "sn" );

         LDAPSortKey sortByFirstName = new LDAPSortKey( "-givenname" );

         LDAPSortKey[] sortOrder = { sortByLastName, sortByFirstName };



         /* Create a server control using that sort key. */

         LDAPSortControl sortCtrl = new LDAPSortControl(sortOrder, 

            true);



         /* Create search constraints to use that control. */

         LDAPSearchConstraints cons = ld.getSearchConstraints();

         cons.setServerControls( sortCtrl );



         /* Perform the search. */

         LDAPSearchResults res = ld.search( MY_BASE, 

            LDAPv3.SCOPE_SUB, MY_FILTER, attrs, false, cons );



         /* Loop through the results until finished. */

         System.out.println( "Sorted Results from Server" );

         System.out.println( "==========================" );

         while ( res.hasMoreElements() ) {



            /* Get the next directory entry. */

            LDAPEntry findEntry = null;

            try {

               findEntry = res.next();



            /* Skip any referrals found for now. */

            } catch ( LDAPReferralException e ) {

               continue;

            } catch ( LDAPException e ) {

               System.out.println( "Error: " + e.toString() );

               continue;

            }



            /* Get the set of attributes for that entry. */

            LDAPAttributeSet findAttrs = findEntry.getAttributeSet();

            Enumeration enumAttrs = findAttrs.getAttributes();



            /* Iterate through the attributes. */

            while ( enumAttrs.hasMoreElements() ) {

               LDAPAttribute anAttr =

                  (LDAPAttribute)enumAttrs.nextElement();



               /* Get the set of values for each attribute. */

               Enumeration enumVals = anAttr.getStringValues();

               if ( enumVals == null ) {

                  System.out.println( "\tNo values." );

                  continue;

               }



               /* Iterate through the values and print each value. */

               String aVal = (String)enumVals.nextElement();

               System.out.print( aVal );

               while (enumVals.hasMoreElements() ) {

                  aVal = (String)enumVals.nextElement();

                  System.out.print( ", " + aVal );

               }

               System.out.print( "\t\t" );

            }

         System.out.println( "" );

         }



         /* Determine if the server sent a control back to you. */

         LDAPControl[] returnedControls = res.getResponseControls();

         if ( returnedControls != null ) {

            for ( int i=0; i<returnedControls.length; i++ ){

               if (!(returnedControls[i] instanceof LDAPSortControl)){

                  continue;

               }

               LDAPSortControl sortRsp = (LDAPSortControl)

                                          returnedControls[i];

               int resultCode = sortRsp.getResultCode;



               /*Check if the result code indicated an error occurred.*/

               if ( resultCode != 0 ) {

                  System.out.println( "Result code: " + resultCode );

                  System.out.println( 

                     LDAPException.errorCodeToString( resultCode ) );



                  /* If the server specified the attribute that 

                  caused the failure, print it out. */

                  String failedAttr = sortRsp.getFailedAttribute();

                  if ( failedAttr != null ) {

                     System.out.println( "Failed on "+failedAttr );

                  } else {

                     System.out.println( "Server did not indicate which

                        " + "attribute caused sorting to fail." );

                  }

               }

            }

         }

         status = 0;

      }

      catch( LDAPException e ) {

         System.out.println( "Error: " + e.toString() );

      }



      /* Done, so disconnect */

      if ( (ld != null) && ld.isConnected() ) {

         try {

            ld.disconnect();

            System.out.println( "" );

         } catch ( LDAPException e ) {

            System.out.println( "Error: " + e.toString() );

         }

   }

      System.exit(status);

   }

}

...

• "Creating the Control"
• "Performing the Search"
• "Example of Using the Persistent Search Control"

• The type of change you want to track. You can specify any of the following (or any combination of the following using a bitwise OR operator):

• ADD indicates that you want to track added entries
• DELETE indicates that you want to track deleted entries
• MODIFY indicates that you want to track modified entries
• MODDN indicates that you want to track renamed entries
• A preference indicating whether you want the server to return all entries that initially matched the search criteria
• A preference indicating whether or not you want entry change notification controls included with every modified entry returned by the server

...

/* Track all types of changes. */

int op = LDAPPersistSearchControl.ADD |

   LDAPPersistSearchControl.MODIFY |

   LDAPPersistSearchControl.DELETE |

   LDAPPersistSearchControl.MODDN;



/* Return only entries that have changed. */

boolean changesOnly = true;



/* Return an "entry change notification" control. */ 

boolean returnControls = true;



/* Mark the control as critical. */

boolean isCritical = true;



/* Create the control. */ 

LDAPPersistSearchControl persistCtrl = new

   LDAPPersistSearchControl( op, changesOnly,

   returnControls, isCritical );

...

1. Get a clone of LDAPSearchConstraints for the current connection by invoking the getSearchConstraints method of the LDAPConnection object.
2. Invoke the setServerControls method for the cloned LDAPSearchConstraints object, and pass in the LDAPPersistSearchControl object that you have constructed.
3. Invoke the search method of the LDAPConnection object, passing in the LDAPSearchConstraints object.

The server returns matching entries as they change. If you specified that you wanted an "entry change notification" control included with each entry, you can get these controls from the server's results. For details, see "Using the Entry Change Notification Control".

import netscape.ldap.*;

import netscape.ldap.controls.*;

import java.util.*;

public class SrchPrst implements Runnable {

   private String hostname;

   private int portnumber;

   public SrchPrst() {

   }



   public static void main( String[] args ) {

      /* Start up a new thread. */

      Thread th = new Thread( new SrchPrst(), "mainConn" );

      th.start();

      System.out.println( "Main thread started." );

   }



   public void run() {

      LDAPConnection ld = new LDAPConnection();

      String hostname = "localhost";

      int portnumber = LDAPv2.DEFAULT_PORT;

      try {

         /* Connect to server */

         ld.connect( 3, hostname, portnumber, "", "" );

         /* Specify that you want to track changes to all entries. */

         String MY_FILTER = "(objectclass=*)";

         String MY_BASE = "o=Airius.com";



         /* Create a persistent search control. */

         int op = LDAPPersistSearchControl.ADD |

            LDAPPersistSearchControl.MODIFY |

            LDAPPersistSearchControl.DELETE |

            LDAPPersistSearchControl.MODDN;

         boolean changesOnly = true;

         boolean returnControls = true;

         boolean isCritical = true;

         LDAPPersistSearchControl persistCtrl = new

               LDAPPersistSearchControl( op, changesOnly,

               returnControls, isCritical );



         /* Create search constraints to use that control. */

         LDAPSearchConstraints cons = ld.getSearchConstraints();

         cons.setServerControls( persistCtrl );

         /* Start the persistent search. */

         LDAPSearchResults res = ld.search( MY_BASE,

            LDAPv3.SCOPE_SUB, MY_FILTER, null, false, cons );



         /* Loop through the results until finished. */

         while ( res.hasMoreElements() ) {



            /* Print any entries that have changed. */

            System.out.println( "\n======= Changed Entry =======" );



            /* Get the next directory entry. */

            LDAPEntry findEntry = res.next();



            /* Get the set of attributes for that entry. */

            LDAPAttributeSet findAttrs = findEntry.getAttributeSet();

            Enumeration enumAttrs = findAttrs.getAttributes();



            /* Iterate through the attributes. */

            while ( enumAttrs.hasMoreElements() ) {

               LDAPAttribute anAttr =

                  (LDAPAttribute)enumAttrs.nextElement();

               String attrName = anAttr.getName();

               System.out.println( "\t" + attrName );



               /* Get the set of values for each attribute. */

               Enumeration enumVals = anAttr.getStringValues();



               /* Iterate through the values and print each value. */

               while (enumVals.hasMoreElements() ) {

                  String aVal = (String)enumVals.nextElement();

                  System.out.println( "\t\t" + aVal );

               }

            }



            /* Get any entry change controls. */

            LDAPControl[] responseCtrls = res.getResponseControls();

            if ( responseCtrls != null ) {

               for ( int i=0; i<responseCtrls.length; i++ ){

                  if (!(responseCtrls[i] instanceof

                        LDAPEntryChangeControl)){

                     continue;

                  }

                  LDAPEntryChangeControl entryCtrl =

                     (LDAPEntryChangeControl) responseCtrls[i];



                  /* Get information on the type of change made. */

                  int changeType = entryCtrl.getChangeType();

                  if ( changeType != -1 ) {

                     System.out.print( "Change made: " );

                     switch ( changeType ) {

                     case LDAPPersistSearchControl.ADD:

                        System.out.println( "Added new entry." );

                        break;

                     case LDAPPersistSearchControl.MODIFY:

                        System.out.println( "Modified entry." );

                        break;

                     case LDAPPersistSearchControl.DELETE:

                        System.out.println( "Deleted entry." );

                        break;

                     case LDAPPersistSearchControl.MODDN:

                        System.out.println( "Renamed entry." );

                        break;

                     }

                  }



                  /* Get the change log number, if present. */

                  int changeNumber = entryCtrl.getChangeNumber();

                  if ( changeNumber != -1 ) {

                     System.out.println( "Change log number: " + 

                        changeNumber );

                  }



                  /* Get the previous DN of the entry, 

                     if a modify DN operation was performed. */ 

                  String oldDN = entryCtrl.getPreviousDN();

                  if ( oldDN != null ) {

                     System.out.println( "Previous DN: " + oldDN );

                  }

               } else {

                  System.out.println( "No entry change control." );

               }

               System.out.println( "\n" );

            }

         }

      }

      catch( LDAPException e ) {

         System.out.println( "Error: " + e.toString() );

      }

   }

}

...

• "Getting the Control"
• "Working with Change Log Numbers"

1. As you retrieve each entry, invoke the getResponseControls method of the LDAPConnection object to retrieve any response controls sent back from the server.

Response controls are passed back as an array of LDAPControl objects.

1. Pass this array of LDAPControl objects as an argument to the LDAPPersistSearchControl.parseResponse static method to retrieve the "entry change notification" control.

• The control with the OID 2.16.840.1.113730.3.4.4 (or the constant netscape.ldap.LDAPControl.PWEXPIRED) is the expired password control.

This control is used if the server is configured to require users to change their passwords when first logging in and whenever the passwords are reset.

If the user is logging in for the first time or if the user's password has been reset, the server sends this control to indicate that the client needs to change the password immediately.

At this point, the only operation that the client can perform is to change the user's password. If the client requests any other LDAP operation, the server sends back an LDAP_UNWILLING_TO_PERFORM result code with an expired password control.

• The control with the OID 2.16.840.1.113730.3.4.5 (or the constant netscape.ldap.LDAPControl.PWEXPIRING) is the password expiration warning control.

This control is used if the server is configured to expire user passwords after a certain amount of time.

The server sends this control back to the client if the client binds using a password that will soon expire. If you invoke the getValue method for this LDAPControl object, the method returns the number of seconds before the password will expire.