LDAP: Matched Values Request Control

The matched values request control described in RFC 3876 provides LDAP clients with a way to filter values that would be returned in a search request. This capability is very useful when the LDAP client must process entries with large numbers of values for a multi-valued attribute. The LDAP client specifies the usual search request parameters:

• baseObject
• scope
• filter
• requested attributes

and in addition may specify other search parameters such as size limit, time limit, and so on.

LDAP clients should always check the root DSE to determine whether a request control is supported before transmitting it to a server For a full description of the search request see:

• LDAP: ldapsearch
• LDAP: Mastering Search Filters
• LDAP: Programming Practices
• LDAP: Search Best Practices

To use the matched values request control, the LDAP client creates the request control using a matched values filter, attaches the request control to the search request, and transmits the search request to the directory server, then processes the response. The server will only return values of attributes matching the matched values filter; attributes need not retrieve all values of a multi-valued attribute and iterate over them. The demonstration of how to use the matched values request control is called MatchedValuesRequestControlExample.java – click on the filename to download.

Test Entry

The test was executed using the following entry. Note the multiple values of the description attribute. The intent of the test is to retrieve the description attribute whose value is "description type 4". Without the matched values request control, the LDAP client would be forced to retrieve all values of the description attribute and iterate over all of the values until a value of "description type 4" was found – not very scalable at all. With the matched values request control, the matched values filter is specified as "(description:caseExactMatch:=description type 4)" and the server responds with a search result entry with a description attribute with only that value, if that value exists.

dn: uid=user.0,ou=People,dc=example,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
postalAddress: Aaren Atp$01251 Chestnut Street$Panama City, DE  50369
postalCode: 50369
description: This is the description for Aaren Atp.
description: description type 1
description: description type 2
description: description type 3
description: description type 4
description: description type 5
description: description type 6
description: description type 7
description: description type 8
description: description type 9
description: description type 10
uid: user.0
employeeNumber: 998
initials: ASA
givenName: Aaren
pager: +1 779 041 6341
mobile: +1 010 154 3228
cn: Aaren Atp
sn: Atp
telephoneNumber: +1 685 622 6202
street: 01251 Chestnut Street
homePhone: +1 225 216 5900
l: Panama City
mail: user.0@maildomain.net
mail: This is the new attribute value.
st: DE

Execute the example

java -cp YOUR_CLASSPATH \
   samplecode.MatchedValuesRequestControlExample \
   --attribute description \
   --baseObject uid=user.0,ou=people,dc=example,dc=com \
   --bindDn uid=user.0,ou=people,dc=example,dc=com \
   --bindPasswordFile /Users/terrygardner/.pwdFile \
   --hostname ldap.example.com \
   --matchedValuesFilter "(description:caseExactMatch:=description type 4)" \
   --port 1389 \
   --scope base

The use of the extensible match filter is not strictly necessary, "(description=description type 4)" would have worked also, since the case matches. The matched values filter supports extensible match filters, but cannot contain a DN argument component.

On my system, this outputs:

[07/Dec/2011:13:29:56 -0500] Connected to LDAP server.
[07/Dec/2011:13:29:56 -0500] MatchedValuesRequestControl is supported.
[07/Dec/2011:13:29:56 -0500] SearchResultEntry(dn='uid=user.0,ou=People,dc=example,dc=com',
  messageID=3, attributes={Attribute(name=description,
  values={'description type 4'})}, controls={})
[07/Dec/2011:13:29:56 -0500] MatchedValuesRequestControlExample
  has completed processing. The result code was: 0 (success)

From the command line with the ldapsearch tool

ldapsearch -D 'uid=user.0,ou=people,dc=example,dc=com' \
  -j ~/.pwdFile -p 1389 -b dc=example,dc=com \
  --matchedValuesFilter 'description=description type 4' \
  '(uid=user.0)'
dn: uid=user.0,ou=People,dc=example,dc=com
description: description type 4

If you are still using the old OpenLDAP ldapsearch tool, it also support the matched values request control with a slightly different syntax:

/usr/bin/ldapsearch -LLLx -D 'uid=user.0,ou=people,dc=example,dc=com' \
  -W  -H ldap://ldap.example.com:1389 \
  -b dc=example,dc=com \
  -E mv='(description:caseExactMatch:=description type 4)' \
  '(uid=user.0)'
Enter LDAP Password:
dn: uid=user.0,ou=People,dc=example,dc=com
description: description type 4