Controls LDAP Controls This chapter demonstrates how to use LDAP controls. For complete examples corresponding to the excerpts shown below, see Controls.java, one of the OpenDJ LDAP SDK examples.

Controls provide a mechanism whereby the semantics and arguments of existing LDAP operations may be extended. One or more controls may be attached to a single LDAP message. A control only affects the semantics of the message it is attached to. Controls sent by clients are termed request controls, and those sent by servers are termed response controls.

Controls Supported LDAP Checking supported features For OpenDJ, the controls supported are listed in the Administration Guide appendix, LDAP Controls. You can access the list of OIDs for supported LDAP controls by reading the supportedControl attribute of the root DSE. $ ldapsearch \ --baseDN "" \ --searchScope base \ --port 1389 \ "(objectclass=*)" supportedControl dn: supportedControl: 1.2.826.0.1.3344810.2.3 supportedControl: 1.2.840.113556.1.4.1413 supportedControl: 1.2.840.113556.1.4.319 supportedControl: 1.2.840.113556.1.4.473 supportedControl: 1.2.840.113556.1.4.805 supportedControl: 1.3.6.1.1.12 supportedControl: 1.3.6.1.1.13.1 supportedControl: 1.3.6.1.1.13.2 supportedControl: 1.3.6.1.4.1.26027.1.5.2 supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1 supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2 supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8 supportedControl: 1.3.6.1.4.1.4203.1.10.1 supportedControl: 1.3.6.1.4.1.4203.1.10.2 supportedControl: 1.3.6.1.4.1.7628.5.101.1 supportedControl: 2.16.840.1.113730.3.4.12 supportedControl: 2.16.840.1.113730.3.4.16 supportedControl: 2.16.840.1.113730.3.4.17 supportedControl: 2.16.840.1.113730.3.4.18 supportedControl: 2.16.840.1.113730.3.4.19 supportedControl: 2.16.840.1.113730.3.4.2 supportedControl: 2.16.840.1.113730.3.4.3 supportedControl: 2.16.840.1.113730.3.4.4 supportedControl: 2.16.840.1.113730.3.4.5 supportedControl: 2.16.840.1.113730.3.4.9 The following excerpt shows couple of methods to check whether the directory server supports a control. [jcp:org.forgerock.opendj.examples.Controls:--- JCite check support ---]

Controls Assertion Assertions The LDAP assertion control lets you specify a condition that must be true in order for the operation you request to be processed normally. The following excerpt shows, for example, how you might check that no description exists on the entry before adding your description. [jcp:org.forgerock.opendj.examples.Controls:--- JCite assertion ---] OpenDJ directory server supports the LDAP assertion control: dn: uid=bjensen,ou=People,dc=example,dc=com description: Created using LDAP assertion control

Controls Authorization ID Authorizations The LDAP Authorization Identity Controls let you get the authorization identity established when you bind to the directory server. The following excerpt shows simple use of the controls. [jcp:org.forgerock.opendj.examples.Controls:--- JCite authzid ---] OpenDJ directory server supports the LDAP Authorization Identity Controls: Binding as uid=bjensen,ou=People,dc=example,dc=com Authorization ID returned: dn:uid=bjensen,ou=People,dc=example,dc=com

Controls Entry change notification Searches Entry change notification Change notification When performing a persistent search, your application can retrieve information using this response control about why the directory server returned the entry. See the Internet-Draft on persistent searches for background information. [jcp:org.forgerock.opendj.examples.Controls:--- JCite psearch ---] OpenDJ directory server supports persistent searches and the entry change notification response control. When another application renames Anne-Louise Barnes's entry, the sample code picks up information from the entry change notification response control: Entry changed: uid=bdobbs,ou=People,dc=example,dc=com Change type: modifyDN Previous DN: uid=abarnes,ou=People,dc=example,dc=com Change number: -1 In this case, Change number: -1 because the server did not set a change number value. OpenDJ directory server does not set the change number value in the response control. If you need to track the order of changes with OpenDJ directory server, read the external change log instead of using the entry change notification response control.

Controls GetEffectiveRights Authorizations Your application can attach the GetEffectiveRights request control to retrieve information about what the directory server permits a user to do. Use this control during a search to see permissions on the entries returned. See the Internet-Draft on the Access Control Model for LDAP for background. [jcp:org.forgerock.opendj.examples.Controls:--- JCite effective rights ---] OpenDJ SDK currently implements the request control, but not the response control. The results are shown as values of the aclRights and more verbose aclRightsInfo attributes. dn: uid=bjensen,ou=People,dc=example,dc=com aclRightsInfo;logs;attributeLevel;selfwrite_delete;cn: acl_summary(main) : access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com , distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: allow all Admin group) aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, objectClass) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied) ( reason : evaluated allow , deciding_aci: Anonymous read-search access) aclRightsInfo;logs;attributeLevel;proxy;cn: acl_summary(main) : access not allowed(proxy) on entry/attr(uid=bjensen,ou=People,dc=example, dc=com, cn) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) (reason: no acis matched the subject ) aclRights;attributeLevel;cn: search:1,read:1,compare:1,write:1,selfwrite_add:1, selfwrite_delete:1,proxy:0 aclRightsInfo;logs;attributeLevel;write;cn: acl_summary(main): access allowed (write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: allow all Admin group) aclRights;entryLevel: add:1,delete:1,read:1,write:1,proxy:0 aclRightsInfo;logs;attributeLevel;search;cn: acl_summary(main): access allowed( search) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access) aclRightsInfo;logs;entryLevel;write: acl_summary(main): access allowed(write ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: allow all Admin group) aclRightsInfo;logs;attributeLevel;selfwrite_add;cn: acl_summary(main ): access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example, dc=com, distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) ( not proxied) ( reason: evaluated allow , deciding_aci: allow all Admin group) aclRightsInfo;logs;entryLevel;add: acl_summary(main): access allowed(add ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: allow all Admin group) aclRightsInfo;logs;attributeLevel;read;cn: acl_summary(main): access allowed( read) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access) cn: Barbara Jensen cn: Babs Jensen aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed( proxy) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: no acis matched the subject ) aclRightsInfo;logs;attributeLevel;compare;cn: acl_summary(main): access allowed (compare) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access) aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access allowed( delete) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to ( uid=kvaughan,ou=People,dc=example,dc=com) (not proxied ) ( reason: evaluated allow , deciding_aci: allow all Admin group)

Controls ManageDsaIT Referrals The ManageDsaIT control, described in RFC 3296, Named Subordinate References in LDAP Directories, lets your application handle references and other special entries as normal entries. Use it when you want to read from or write to reference or special entry. [jcp:org.forgerock.opendj.examples.Controls:--- JCite manage DsaIT ---] OpenDJ directory server supports the ManageDsaIT Request Control. To use the example entry create a new base DN, dc=ref,dc=com before you import the data: Referral without the ManageDsaIT control. Reference: [ldap:///dc=example,dc=com??sub?] Referral with the ManageDsaIT control. dn: dc=references,dc=ref,dc=com

Controls Matched values Groups RFC 3876, Returning Matched Values with the LDAPv3, describes a control that lets your application pass a filter in a search request getting a multivalued attribute such that the directory server only returns attribute values that match the filter. Barbara Jensen's entry contains two common name values, Barbara Jensen and Babs Jensen. The following excerpt retrieves only the latter. [jcp:org.forgerock.opendj.examples.Controls:--- JCite matched values ---] OpenDJ directory server supports the matched values request control. Reading entry with matched values request. dn: uid=bjensen,ou=People,dc=example,dc=com cn: Babs Jensen

Controls Microsoft LDAP Server Notification Control The Microsoft LDAP Server Notification Control with OID 1.2.840.113556.1.4.528 can be used to register a change notification request for a search on Microsoft Active Directory. [jcp:org.forgerock.opendj.examples.Controls:--- JCite ADNotification ---] When you run the search against Active Directory and then create, update, and delete a new user Active Directory notifies you of changes to directory data.

Controls Password expired LDAP Password policy A directory server can return the Password Expired Response Control, described in the Internet-Draft Password Policy for LDAP Directories, when a bind fails because the password has expired. In order to see this, you must configure the directory to expire Barbara Jensen's password. [jcp:org.forgerock.opendj.examples.Controls:--- JCite password expired ---] OpenDJ directory server supports the Password Expired Response Control. To obtain the following output from the excerpt, you can change the default password policy configuration to set a short maximum password age, change Barbara Jensen's password, and wait for it to expire. See the OpenDJ Administration Guide procedure explaining how To Adjust the Default Password Policy for an example of how to adjust the maximum password age. Password expired for uid=bjensen,ou=People,dc=example,dc=com

Controls Password expiring LDAP Password policy The Password Expiring Response Control, described in the Internet-Draft Password Policy for LDAP Directories, warns your application during a bind that the password used will soon expire. [jcp:org.forgerock.opendj.examples.Controls:--- JCite password expiring ---] OpenDJ directory server supports the Password Expiring Response Control. To obtain the following output from the excerpt, you can change the default password policy configuration to set a maximum password age and a warning interval, change Barbara Jensen's password, and wait until you enter the warning interval before password expiration. See the OpenDJ Administration Guide procedure explaining how To Adjust the Default Password Policy for an example of how to adjust the maximum password age. Also set a short password-expiration-warning-interval value. Password for uid=bjensen,ou=People,dc=example,dc=com expires in 237 seconds.

Controls Password policy LDAP Password policy The Behera Internet-Draft, Password Policy for LDAP Directories, describes Password Policy Request and Response Controls. You send the request control with a request to let the directory server know that your application can handle the response control. The directory server sends the response control on applicable operations to communicate warnings and errors. [jcp:org.forgerock.opendj.examples.Controls:--- JCite password policy ---] OpenDJ directory server supports the Password Policy Controls. To obtain the output from the excerpt, you can change the default password policy configuration to set a maximum password age and a warning interval, change Barbara Jensen's password, and then run the example during the warning interval and after the password has expired. See the OpenDJ Administration Guide procedure explaining how To Adjust the Default Password Policy for an example of how to adjust the maximum password age. Also set a short password-expiration-warning-interval value. For a warning: Password policy warning timeBeforeExpiration, value 237 for uid=bjensen,ou=People,dc=example,dc=com For an error: Password policy error passwordExpired for uid=bjensen,ou=People,dc=example,dc=com

Controls Permissive modify Modifications Permissive modify Microsoft defined a Permissive Modify Request Control that relaxes some constraints when your application performs a modify operation and tries to add an attribute that already exists, or to delete an attribute that does not exist. [jcp:org.forgerock.opendj.examples.Controls:--- JCite permissive modify ---] OpenDJ directory server supports the Permissive Modify Request Control: Permissive modify did not complain about attempt to add uid: bjensen to uid=bjensen,ou=People,dc=example,dc=com.

Controls Persistent search Searches Persistent search Change notification See .

Controls Post-read Searches Handling results RFC 4527, LDAP Read Entry Controls, describes the post-read controls that let your application get the content of an entry immediately after modifications are applied. [jcp:org.forgerock.opendj.examples.Controls:--- JCite post read ---] OpenDJ directory server supports these controls: dn: uid=bjensen,ou=People,dc=example,dc=com description: Using the PostReadRequestControl

Controls Pre-read Assertions RFC 4527, LDAP Read Entry Controls, describes the pre-read controls that let your application get the content of an entry immediately before modifications are applied. [jcp:org.forgerock.opendj.examples.Controls:--- JCite pre read ---] OpenDJ directory server supports these controls: dn: uid=bjensen,ou=People,dc=example,dc=com mail: bjensen@example.com

Controls Proxied authorization Authorizations Proxied authorization provides a standard control as defined in RFC 4370 (and an earlier Internet-Draft) for binding with the user credentials of a proxy, who carries out LDAP operations on behalf of other users. You might use proxied authorization, for example, to have your application bind with its credentials, and then carry out operations as the users who login to the application. [jcp:org.forgerock.opendj.examples.Controls:--- JCite proxied authzv2 ---] OpenDJ supports proxied authorization, and the example works with the sample data: dn: uid=bjensen,ou=People,dc=example,dc=com description: Done with proxied authz

Controls Server-side sort Searches Server-side sort Browsing Sorting The server-side sort controls are described in RFC 2891, LDAP Control Extension for Server Side Sorting of Search Results. If possible, sort on the client side instead to reduce load on the server. If not, then you can request a server-side sort. [jcp:org.forgerock.opendj.examples.Controls:--- JCite server-side sort ---] OpenDJ directory server supports server-side sorting: dn: uid=ajensen,ou=People,dc=example,dc=com cn: Allison Jensen dn: uid=bjensen,ou=People,dc=example,dc=com cn: Barbara Jensen cn: Babs Jensen dn: uid=bjense2,ou=People,dc=example,dc=com cn: Bjorn Jensen dn: uid=gjensen,ou=People,dc=example,dc=com cn: Gern Jensen dn: uid=jjensen,ou=People,dc=example,dc=com cn: Jody Jensen dn: uid=kjensen,ou=People,dc=example,dc=com cn: Kurt Jensen dn: uid=rjense2,ou=People,dc=example,dc=com cn: Randy Jensen dn: uid=rjensen,ou=People,dc=example,dc=com cn: Richard Jensen dn: uid=tjensen,ou=People,dc=example,dc=com cn: Ted Jensen # Entries are sorted.

Controls Simple paged results Searches Simple paged results Browsing RFC 2696, LDAP Control Extension for Simple Paged Results Manipulation, defines a control for simple paging of search results that works with a cookie mechanism. [jcp:org.forgerock.opendj.examples.Controls:--- JCite simple paged results ---] OpenDJ directory server supports getting simple paged results: # Simple paged results: Page 1 dn: uid=ajensen,ou=People,dc=example,dc=com cn: Allison Jensen dn: uid=bjense2,ou=People,dc=example,dc=com cn: Bjorn Jensen dn: uid=bjensen,ou=People,dc=example,dc=com cn: Barbara Jensen cn: Babs Jensen # Simple paged results: Page 2 dn: uid=gjensen,ou=People,dc=example,dc=com cn: Gern Jensen dn: uid=jjensen,ou=People,dc=example,dc=com cn: Jody Jensen dn: uid=kjensen,ou=People,dc=example,dc=com cn: Kurt Jensen # Simple paged results: Page 3 dn: uid=rjense2,ou=People,dc=example,dc=com cn: Randy Jensen dn: uid=rjensen,ou=People,dc=example,dc=com cn: Richard Jensen dn: uid=tjensen,ou=People,dc=example,dc=com cn: Ted Jensen

Controls Subentries LDAP Subentries RFC 3672, Subentries in LDAP, describes subentries and also the subentries request control. When you perform a search without the control and visibility set to TRUE, subentries are only visible in searches with SearchScope.BASE_OBJECT. [jcp:org.forgerock.opendj.examples.Controls:--- JCite subentries ---] OpenDJ directory server supports the control. dn: cn=Bronze Class of Service,dc=example,dc=com cn: Bronze Class of Service subtreeSpecification: { base "ou=People", specificationFilter "(classOfService= bronze)" } dn: cn=Silver Class of Service,dc=example,dc=com cn: Silver Class of Service subtreeSpecification: { base "ou=People", specificationFilter "(classOfService= silver)" } dn: cn=Gold Class of Service,dc=example,dc=com cn: Gold Class of Service subtreeSpecification: { base "ou=People", specificationFilter "(classOfService= gold)" }

Controls Subtree delete Deletes Subtree delete The subtree delete request control, described in the Internet-Draft Tree Delete Control, lets your application delete an entire branch of entries starting with the entry you target for deletion. [jcp:org.forgerock.opendj.examples.Controls:--- JCite tree delete ---] OpenDJ directory server supports the subtree delete control: Successfully deleted ou=Apps,dc=example,dc=com and all entries below.

Controls Virtual list view Searches Virtual list view Browsing Sorting The virtual list view controls are intended to be used by applications that let users browse lists of directory entries. The Internet-Draft LDAP Extensions for Scrolling View Browsing of Search Results describes the controls. The virtual list view request control is used in conjunction with the server-side sort control such that the subset of entries the directory server returns from a search are a window into the full sorted list. [jcp:org.forgerock.opendj.examples.Controls:--- JCite vlv ---] OpenDJ directory server supports the virtual list view controls. In order to set up OpenDJ directory server to produce the following output with the example code, use OpenDJ Control Panel > Manage Indexes > New VLV Index... to set up a virtual list view index for people by last name, using the filter (|(givenName=*)(sn=*)), and sorting first by surname, sn, in ascending order, then by given name also in ascending order. dn: uid=skellehe,ou=People,dc=example,dc=com givenName: Sue sn: Kelleher dn: uid=ejohnson,ou=People,dc=example,dc=com givenName: Emanuel sn: Johnson dn: uid=ajensen,ou=People,dc=example,dc=com givenName: Allison sn: Jensen dn: uid=bjense2,ou=People,dc=example,dc=com givenName: Bjorn sn: Jensen dn: uid=bjensen,ou=People,dc=example,dc=com givenName: Barbara sn: Jensen # Entries are sorted. # Position in list: 92/150

Controls Generic OpenDJ LDAP SDK supports many controls, but you might still need to work with additional controls. If so, then in some cases you can use the GenericControl class when adding the control to your request. The following example uses a GenericControl to add a pre-read request control when replacing the description on a user's entry. OpenDJ LDAP SDK already implements the pre-read request control, as shown in . The example is of interest mainly because it shows that the values that you pass when using a GenericControl must be prepared as indicated in the specification of the control. [jcp:org.forgerock.opendj.examples.UseGenericControl:--- JCite ---] When you run this example against a user entry in OpenDJ directory server, you see something like the following result. # Before modification dn: uid=bjensen,ou=People,dc=example,dc=com description: Original description # After modification dn: uid=bjensen,ou=People,dc=example,dc=com description: A new description The GenericControl class is useful with controls that do not require you to encode complex request values, or decode complex response values. If the control you want to you requires complex encoding or decoding, you might have to implement org.forgerock.opendj.ldap.controls.Control.