Chapter 21 Directory Proxy Server Connection Handlers

Incoming connections to Directory Proxy Server are categorized into connection handlers according to a set of criteria. A connection handler defines the resource limits and request filters that apply to the connection, and the data views that are exposed to the connection.

This chapter covers the following topics:

• Criteria for Allocating a Connection to a Connection Handler

• Data Views for Connection Handlers

• Resource Limits Policies for Connection Handlers

• Request Filtering Policies for Connection Handlers

Criteria for Allocating a Connection to a Connection Handler

An instance of Directory Proxy Server can have many connection handlers. When a client connects to Directory Proxy Server, the proxy evaluates whether the attributes of the connection match the criteria of one of the connection handlers. When a match is found, the connection is classified into that connection handler. All of the policies defined for that connection handler apply to the connection. Operations performed through that connection are exposed to all of the data views or to a list of data views defined by the connection handler.

After being classified into a connection handler, a connection can be automatically reclassified into another connection handler by Directory Proxy Server. For example, if a client connects anonymously, the connection is allocated to the connection handler configured for anonymous connections. If the client later provides a bind DN on the same connection, the connection can be reallocated to another connection handler. Similarly, a non-secure LDAP connection is initially classified into a connection handler for non-secure connections. If the client uses startTLS to promote the connection to secure mode, the connection is automatically reclassified into a connection handler for secure connections.

A connection is evaluated against connection handlers in order of the priority of the connection handler. Priority one is the highest priority connection handler. The connection is classified into the first connection handler for which there is a match. Connection handlers with the most specific criteria should have a higher priority than those with less specific or more general criteria. For example, a connection handler that specifies a bind DN should have a higher priority than a connection handler that specifies a simple bind.

If a connection does not match the criteria of any configured connection handler, the connection is allocated to the default connection handler. The criteria of the default connection handler cannot be modified. In addition, the default connection handler cannot be disabled or deleted. However, the policies and data views of the default connection handler can be changed.

The default connection handler is the lowest priority connection handler. If a new connection handler is created without a priority, the new connection handler is given a higher priority than the default connection handler. If two connection handlers have the same priority, the order in which the connection is evaluated against them is not specified.

The criteria expression of a connection handler is a logical AND between criteria of different types and a logical OR between criteria of the same type. For example, if a criteria is specified for client IP address and a criteria is set for client domain name, both of the criteria must be met. However, if two criteria are set for client IP address, either, not both, of the criteria must be met.

The following list summarizes the criteria used to classify connections into connection handlers. For information about how to configure the criteria, see Creating, Configuring, and Deleting Connection Handlers in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

• Client IP address and mask. A set of IPv4 or IPv6 address masks. The IP address of a client connection must match at least one of the masks in order for the connection to be accepted by the connection handler.

  The IP address can be in one of the following formats:

  • IP address in dotted decimal form. For example, 129.153.129.14.

  • IP address and bits, in the form of network number/mask bits. For example, 129.153.129.0/24.

  • IP address and quad, in the form of a pair of dotted-decimal quads. For example, 129.153.129.0/255.255.255.128.

  • All addresses:ALL, a catch-all for clients that are not placed into other, higher priority, groups.

  • 0.0.0.0. This address is for groups for which initial membership is not considered. For example, for groups that clients switch to after their initial bind.

  • IP address of the local host. IP address 127.0.0.1 is the IP address of a client that is running on the same machine as Directory Proxy Server.

• Client domain name. A set of domain names. A client network domain must match at least one of the suffixes in order for the connection to be accepted by the connection handler.

  In order to be able to filter the client's domain name, Directory Proxy Server must be able to convert the incoming IP address into the fully qualified domain name. If the naming service returns a hostname without the domain name, Directory Proxy Server cannot filter the client's domain name.

  Directory Proxy Server does not assume any domain suffix, therefore the fully qualified domain name must be provided. A domain name suffix with a leading period, for example, .sun.com, will cause all hosts with domain names that end in that suffix to match.

  The domain name can be in one of the following formats:

  • Full name, for example, box.eng.sun.com.

  • Suffix name, for example, .eng.sun.com. If the suffix name is used to identify clients, ensure that DNS is set up to return fully qualified names to the DNS queries.

  • Fully qualified name of the local host. This criteria is for a client that is running on the same machine as Directory Proxy Server.

• Bind DN. A regular expression that must be matched by the bind DN of a client.

  For example, the following regular expression could be used as a bind DN criteria for a connection handler: uid=(.*),dc=example,dc=com. A client that binds with a uid such as uid=user1,dc=example,dc=com matches the criteria and can be allocated to the connection handler. A client that binds with another DN such as ou=accounts,dc=example,dc=com does not match the criteria and cannot be allocated to the connection handler.

• LDAP search filter. A search filter that the entry of a bound client must match.

  For example, the following filter could be used as a criteria for a connection handler: uid>=1000. Bound clients with a uid that matches the filter can be allocated to the connection handler.

• Authentication method. An authentication method that must match the client entry in order for the connection to be accepted by the connection handler.

  The authentication method can be one of the following:

  • SIMPLE

  • SASL/EXTERNAL

  • Anonymous

• IP port. A set of IP port numbers. A client connection must come through one of the specified ports in order for the connection to be accepted by the connection handler.

• SSL connection. A flag indicating whether or not client connections must use SSL in order to be accepted by the connection handler.

Data Views for Connection Handlers

When a connection is allocated to a connection handler, requests on the connection are exposed to a list of data views configured for that connection handler. The list of data views for a connection handler can contain zero, one, or multiple data views.

If the list of data views is empty, requests on the connection are not distributed to any data view. Applications using the connection cannot access any data and a No such Object error is returned.

If the list of data views contains multiple data views, requests on the connection are distributed to the data view that most specifically corresponds to the target DN of the request. For example, in Figure 21–1, requests on a connection in connection-handler-1 can be distributed to data-view-2, data-view-3 or data-view-4. However, if a search request has a target DN of ou=people,dc=example,dc=com, the request is distributed either to data-view-3 or to data-view-4.

Figure 21–1 List of Data Views in a Connection Handler

Affinity can be defined between a client connection and the data view selected to respond to requests on that connection. This feature is called data view affinity. When data view affinity is enabled, successive requests on a client connection are exposed exclusively to the data view used for the first request on that connection.

When data view affinity is enabled it takes precedence over other types of routing. For example, in Figure 21–1, a search request with a target DN of ou=computer,dc=example,dc=com is exposed to data-view-2. All subsequent requests on that client connection are exposed exclusively to data-view-2. If a subsequent request on that client connection has a target DN of ou=people,dc=example,dc=com, the request is exposed to the data view for ou=computer,dc=example,dc=com, not the data view for ou=people,dc=example,dc=com.

For information about how to configure data view affinity, see To Configure Affinity for Data Views in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Resource Limits Policies for Connection Handlers

A resource limits policy defines the maximum resources that Directory Proxy Server can process for a given connection handler. By using this type of connection handler policy, you can limit the resources allocated to connections, requests, and referrals.

A connection handler can have zero or one resource limits policy. If no resource limits policy is defined, no limits are applied to connections, requests and referrals. For information about how to configure resource limits policies and examples of resource limits policies, see Creating and Configuring a Resource Limits Policy in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

The following list summarizes the resource limits that can be configured:

• Connections

  • Maximum number of connections.

  • Maximum number of simultaneous connections from a single client.

  • Maximum number of operations per connection. If a client exceeds the maximum number of operations on one connection, the connection is closed by Directory Proxy Server.

  • Maximum number of simultaneous operations per connection.

    If the maximum number of simultaneous operations per connection is 1, clients must perform synchronous operations. Additional requests for simultaneous operations, except for requests to abandon an operation, will fail with a Server Busy error.

• Searches

  • Maximum permitted size of a search operation result

  • Maximum permitted duration of a search operation

  • Minimum length of a substring allowed in a search filter

  • Customized search limits, described in Customized Search Limits

• Referrals

  • Maximum number of hops when following referrals

  • Bind policy to be applied when referrals are followed:

    • Use password if supplied, else follow the referral as anonymous

    • Always follow the referral as anonymous

  • Policy applied when a referral is returned by the server:

    • Follow referrals

    • Forward referrals to the client

    • Discard referrals

For information about how to configure a resource limits policy, see Creating and Configuring a Resource Limits Policy in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Customized Search Limits

Customized limits can be defined for search operations, based on the search base and search scope. If the target DN of a search is specified in a list, and the scope of a search is one-level or subtree, the maximum size of the search result can be configured.

Custom search limits are defined for a specific resource limits policy. If the resource limits policy is deleted, the custom search limits defined for that policy are also deleted. If custom search limits are not specified, standard search size limits are applied.

Request Filtering Policies for Connection Handlers

Request filtering policies control access of clients to data. A connection handler can reference zero or one request filtering policy.

The following aspects of client access can be defined by using this type of connection handler policy:

• The types of operation that clients are allowed to perform or are prohibited from performing.

  Each of the following types of operation can be allowed or prohibited: add, bind, compare, delete, extended operations, modify, modify DN, search, and search based on inequality filters.

• Attributes that are allowed or prohibited from being used in search filters and compare operations.

  All attributes can be permitted in search filters and compare operations, or a list of attributes can be permitted or prohibited.

• The scope of search operations.

  The scope can be the base DN, one level below the base DN, or the entire subtree below the base DN.

• The subtrees that clients are allowed to access or are prohibited from accessing.

  For information, see Subtrees in the Request Filtering Policy.

• Entries that can be accessed in search operations and data that can be returned by search operations.

  For information, see Search Data Hiding Rules in the Request Filtering Policy.

For information about how to configure a request filtering policy, see Creating and Configuring Request Filtering Policies and Search Data Hiding Rules in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Subtrees in the Request Filtering Policy

The request filtering policy is configured with one or more allowed subtrees and zero, one, or more prohibited subtrees. The subtrees identify the part of a data view that can be accessed by clients.

Allowed Subtrees

An allowed subtree is specified by a minimum base DN. Clients are permitted to perform operations on entries at the minimum base DN or below the minimum base DN. By default, the minimum base DN is the root DN.

If a client requests a search operation that is targeted at a DN superior to the minimum base DN, Directory Proxy Server rewrites the DN to target the minimum base DN. If a client performs any other operation that is targeted at a DN superior to the minimum base DN, the operation is denied.

Prohibited Subtrees

A prohibited subtree is a branch of the allowed subtree that cannot be accessed by the client. The base DN of a prohibited subtree must be subordinate to the minimum base DN of an allowed subtree. If a client performs an operation that is targeted at a prohibited subtree, the operation is denied.

Search Data Hiding Rules in the Request Filtering Policy

Rules that determine how to return the result of a search operation to a client are called search data hiding rules. For information about creating search data hiding rules, see To Create Search Data Hiding Rules in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

The result of a search operation can be returned in one of the following ways:

• The target entry is not returned

• The target entry is returned but the specified attributes are filtered out

• The target entry is returned but the unspecified attributes are filtered out

Search data hiding rules can be applied to the following entries:

• Entries with the specified DN

• Entries with the specified DN pattern

• Entries with a specified attribute name/attribute value pair (attrName:attrValue)

Search data hiding rules are defined for a given request filtering policy and cannot be used by another request filtering policy. If a request filtering policy is deleted, its associated search data hiding rules are automatically deleted. Zero, one or multiple search data hiding rules can be defined in one request filtering policy.