LDAP: Client Connection Policies


A Client Connection Policy controls the portions of the DIT a client can access and resource limits on what clients can do with data stored on the server. Clients are subject to one Client Connection Policy at a given time. Servers are distributed with a default Client Connection Policy. Groups of users or clients can be subject to a client connection policy, which reduces the amount of configuration required.

This article will describe LDAP client connections, authentication using LDAP, connection criteria, and client connection policies. An example is given at the end.

Client Connections

A connection from an LDAP comprises:

  • the IP address of the client
  • the connection handler handling the connection from the client
  • the protocol in use by the client
  • the communication security level
  • the authentication type
  • the authentication security level
  • the SASL mechanism if the authentication type is SASL
  • the base object above the authenticated distinguished name
  • the distinguished name of a group of which the authenticated client distinguished name is a member
  • filters which match the distinguished name of authenticated clients
  • privileges held by an authenticated client


Clients authenticate to Directory Server using the BIND operation. All connections are unauthenticated when they are first established. The authorization state of a connection is changed using the BIND operation. When a BIND operation is received, the Directory Server resets the authorization state of a connection. After a BIND operation is successful, the authorization state of the connection is set to that associated with the BIND distinguished name. Subsequent BIND operations on the connection immediately reset the authorization state to unauthenticated. If clients use LDAPv2, BIND must be the first operation on a connection and no subsequent BIND operations are allowed. LDAPv3 allows multiple BIND operations, subject to certain conditions. All new code should use LDAPv3.

All uncompleted operations must complete or be ABANDONed before a BIND request will be processed by the server. Clients are prohibited from transmitting requests until the BIND operation completes. Servers are prohibited from processing requests before a BIND completes.
Multiple BIND requests are required for multi-stage BIND operations

For more information, see: LDAP: Authentication Best Practices.

Connection Criteria

A connection which matches user-defined criteria is said to meet the connection criteria. The collection of user-defined criteria is known as a Connection Criteria object. Clients connections which meet no defined collection of criteria are subject to the default Client Connection Policy because the default Client Connection Policy has no Connection Criteria object assigned. A collection of criteria is specified by creating a Connection Criteria object and setting properties of the object; or by setting properties of an existing Connection Criteria. Connection Criteria objects are created, deleted, or modified using the dsconfig command line tool or the Web Console.

Client Connection Policies

A Connection Criteria object uses known client connection parameters to classify a client connection. Client connections are subject to a given Client Connection Policy if the client connection matches the Connection Criteria object assigned to the policy; the connection may be said to “meet connection criteria”.

Client Connection Policies are assigned when:

  • A client connects
  • A BIND request is received from the client
  • The client use the StartTLS extended request to promote a non-secure connection to a secure connection


Administrators desire to classify connections from an application called “Email Application”. The source IP addresses of all application instances are 10.1.1.* and 10.1.0.*. The application uses SSL to connect to the server and authenticates with a simple BIND operation that uses a single distinguished name, that is, all instances of the application use one distinguished name to authenticate.

Create the Connection Criteria

Use dsconfig to create a Connection Criteria object which matches the connection parameters described above for the email application, that is, the source IP addresses (the IP addresses from which email application LDAP connections originate), the fact that the applications always use secure connections (SSL), the fact that the applications always use a simple BIND operation using a known DN:

$ dsconfig create-connection-criteria                      \
   --criteria-name "Email Application Connection Criteria" \
   --type simple                                           \
   --set "description:Connections which meet these criteria are connections from one of the Email Application instances."                              \
   --set included-client-address:               \
   --set included-client-address:               \
   --set communication-security-level:secure-only          \
   --set user-auth-type:simple                             \
   --set authentication-security-level:secure-only         \
   --set "included-user-base-dn:cn=Email Applications,ou=Applications,o=servers"

Create the Client Connection Policy

Administrators wish to restrict the Email Application to BIND, SEARCH, and COMPARE operations and to restrict the maximum number of entries the application can retrieve with one request to 100. A Client Connection Policy is used to constrain the application. The client connection policy below allows only BIND, COMPARE, and SEARCH operations, and restricts the clients which match the specified client connection policy (created above and referenced in the client connection policy) to 100 entries per search request.

dsconfig create-client-connection-policy                              \
  --policy-name "Email Application Client Connection Policy"          \
  --set "description:Restrictions on the Email Application instances" \
  --set enabled:true                                                  \
  --set evaluation-order-index:100                                    \
  --set "connection-criteria:Email Application Connection Criteria"   \
  --set allowed-operation:bind                                        \
  --set allowed-operation:compare                                     \
  --set allowed-operation:search                                      \
  --set allowed-auth-type:simple                                      \
  --set maximum-search-size-limit:100

test the new Client Connection Policy

Use ldapsearch to authenticate and search. Note that the parameters to the ldapsearch command match the parameters that will be used by the email applications.

$ ldapsearch -h ldap.example.com                                  \
             -p 1636                                              \
             -D 'cn=email applications,ou=applications,o=servers' \
             --useSSL --trustAll -b '' -s base '(&)' 1.1

View the results in the access log:

BIND RESULT conn=54 op=0 msgID=1 version="3" dn="cn=email applications,ou=applications,o=servers" authType="SIMPLE" resultCode=0 etime=1.377 authDN="cn=email applications,ou=applications,o=servers" clientConnectionPolicy="Email Application Client Connection Policy"

Attempt to modify an entry. The client connection policy will prevent the user with the authorization state associated with the email application from modifying an entry.

$ ldapmodify -h ldap.example.com                                  \
             -p 1636                                              \
             -D 'cn=email applications,ou=applications,o=servers'  \
             -w 'password'                                        \
             --useSSL                                             \
dn: cn=admin,o=servers
changetype: modify
add: description
description: some text.
# Processing MODIFY request for cn=admin,o=servers
The client connection policy associated with the client connection does not allow modify operations to be processed
Result Code:  50 (Insufficient Access Rights)
Diagnostic Message:  The client connection policy associated with the client connection does not allow modify operations to be processed

About Terry Gardner

Terry Gardner was a leading directory services architect with experience with many large scale directory services installations and messaging server installations, and was a Subject Matter Expert in the field of Directory Services and Solaris (operating system) performance. Mr. Gardner also participated in the open-source software community. Mr. Gardner passed away in December, 2013.
This entry was posted in computing, LDAP, UnboundID and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s